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

package/dist/commands/download.js

@@ -11,279 +11,718 @@ import { Command, Flags } from '@oclif/core';
 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 { 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';
+function defaultOutputDirForVersion(versionTag) {
+    const safe = versionTag.replace(/[/\\]/g, '-');
+    return `./nocobase-${safe}`;
+}
+async function pathExists(target) {
+    try {
+        await fsp.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function defaultDockerRegistryForLang(lang) {
+    return String(lang ?? '').trim() === 'zh-CN'
+        ? DEFAULT_DOCKER_REGISTRY_ZH_CN
+        : DEFAULT_DOCKER_REGISTRY;
+}
+function argvHasToken(argv, tokens) {
+    return tokens.some((t) => argv.includes(t));
+}
+function gitRefForVersion(versionSpec) {
+    const versionToRef = {
+        latest: 'main',
+        beta: 'next',
+        alpha: 'develop',
+    };
+    return versionToRef[versionSpec] || versionSpec;
+}
+/** `build-dts` only applies when `build` is true and source is npm/git. */
+function normalizeBuildDts(source, build, wantDts) {
+    if (source !== 'npm' && source !== 'git') {
+        return false;
+    }
+    return Boolean(build && wantDts);
+}
+function downloadSourceLabel(source) {
+    switch (source) {
+        case 'docker':
+            return 'Docker image';
+        case 'npm':
+            return 'npm package';
+        case 'git':
+            return 'Git repository';
+        default:
+            return source;
+    }
+}
+function normalizeDockerPlatform(value) {
+    const text = String(value ?? '').trim();
+    if (text === 'linux/amd64' || text === 'linux/arm64') {
+        return text;
+    }
+    return DEFAULT_DOCKER_PLATFORM;
+}
+function dockerPlatformArg(value) {
+    const platform = normalizeDockerPlatform(value);
+    if (platform === 'auto') {
+        return undefined;
+    }
+    return platform;
+}
+const EXTERNAL_COMMAND_LOADING_DELAY_MS = 8_000;
+const EXTERNAL_COMMAND_LOADING_UPDATE_MS = 15_000;
 export default class Download extends Command {
-    static description = 'Scaffold or fetch NocoBase: npm (create-nocobase-app), docker (image pull), or git (shallow clone).';
+    _flags;
+    preparationTaskActive = false;
+    static description = 'Scaffold or fetch NocoBase from npm, Docker, or Git. `--version` is the shared version input: package version for npm, image tag for Docker, and git ref for Git.';
     static examples = [
         '<%= config.bin %> <%= command.id %>',
-        '<%= config.bin %> <%= command.id %> -y --source npm --version latest',
-        '<%= config.bin %> <%= command.id %> --source npm --version latest',
-        '<%= config.bin %> <%= command.id %> --source npm --version latest --output-dir=./app',
-        '<%= config.bin %> <%= command.id %> --source docker --version latest --docker-registry=nocobase/nocobase',
-        '<%= config.bin %> <%= command.id %> --source git --version latest --git-url=https://github.com/nocobase/nocobase.git',
+        '<%= config.bin %> <%= command.id %> -y --source npm --version alpha',
+        '<%= config.bin %> <%= command.id %> -y --source npm --version alpha --no-build',
+        '<%= config.bin %> <%= command.id %> --source npm --version alpha',
+        '<%= config.bin %> <%= command.id %> --source npm --version alpha --output-dir=./app',
+        '<%= config.bin %> <%= command.id %> --source docker --version alpha --docker-registry=nocobase/nocobase --docker-platform=linux/arm64',
+        '<%= config.bin %> <%= command.id %> -y --source docker --version alpha --docker-save -o ./docker-images',
+        '<%= config.bin %> <%= command.id %> --source git --version alpha --git-url=git@github.com:nocobase/nocobase.git',
+        '<%= config.bin %> <%= command.id %> --source git --version fix/cli-v2',
+        '<%= config.bin %> <%= command.id %> -y --source git --version fix/cli-v2 --no-build',
+        '<%= config.bin %> <%= command.id %> -y --source npm --version alpha --build-dts',
+        '<%= config.bin %> <%= command.id %> -y --source npm --version alpha --npm-registry=https://registry.npmmirror.com',
     ];
     static flags = {
         yes: Flags.boolean({
             char: 'y',
-            description: 'Skip interactive prompts; use flags only (non-TTY implies -y)',
+            description: 'Use defaults and skip interactive prompts.',
+            default: false,
+        }),
+        verbose: Flags.boolean({
+            description: 'Show detailed command output',
+            default: false,
+        }),
+        'no-intro': Flags.boolean({
+            hidden: true,
+            description: 'Skip command intro when invoked by another CLI command',
             default: false,
         }),
         source: Flags.string({
             char: 's',
-            description: 'Distribution: npm runs create-nocobase-app, docker runs docker pull, git clones the repository',
+            description: 'How to get NocoBase: Docker image, npm package, or Git repository.',
             options: ['docker', 'npm', 'git'],
             required: false,
         }),
         version: Flags.string({
             char: 'v',
-            description: 'npm: dist-tag or version for create-nocobase-app; docker: image tag; git: branch or tag (latest→main, beta→next, alpha→develop); default: latest',
+            description: 'Shared version input. For npm this is the package version, for Docker the image tag, and for Git a git ref such as a branch name (for example: alpha, beta, latest, fix/cli-v2).',
         }),
         replace: Flags.boolean({
             char: 'r',
-            description: 'npm/git: delete the target project directory if it exists, then scaffold or clone again; docker: ignored',
+            description: 'Replace the target directory if it already exists.',
             default: false,
         }),
-        'dev': Flags.boolean({
-            description: 'npm: install devDependencies in create-nocobase-app and run a non-production yarn install; git/docker: ignored',
+        'dev-dependencies': Flags.boolean({
+            char: 'D',
+            allowNo: true,
+            description: 'Install development dependencies for npm/git source installs.',
             default: false,
         }),
         'output-dir': Flags.string({
             char: 'o',
-            description: 'npm/git: output directory (relative to cwd); default ./nocobase-<version> using the same value as --version; docker: ignored',
+            description: 'Download target directory, or Docker tarball directory when --docker-save is enabled.',
         }),
         'git-url': Flags.string({
-            description: 'git: remote URL to clone (default: https://github.com/nocobase/nocobase.git)',
+            description: 'Git repository URL to clone when --source git is used.',
         }),
         'docker-registry': Flags.string({
-            description: 'docker: image reference without tag (default: nocobase/nocobase); use -v for the tag, e.g. ghcr.io/nocobase/nocobase',
+            description: 'Docker image repository to pull when --source docker is used.',
+        }),
+        'docker-platform': Flags.string({
+            description: 'Docker image platform to pull; use auto to let Docker choose.',
+            options: ['auto', 'linux/amd64', 'linux/arm64'],
+        }),
+        'docker-save': Flags.boolean({
+            allowNo: true,
+            description: 'Also save the pulled Docker image as a tarball.',
+            default: false,
+        }),
+        'npm-registry': Flags.string({
+            description: 'npm registry for npm/git downloads and dependency installation.',
+        }),
+        'build': Flags.boolean({
+            allowNo: true,
+            description: 'Build npm/git source after dependencies are installed.',
+            default: true,
         }),
+        'build-dts': Flags.boolean({
+            description: 'Generate TypeScript declaration files during the npm/git build.',
+            default: false,
+        }),
+    };
+    static prompts = {
+        source: {
+            type: 'select',
+            message: 'How would you like to get NocoBase?',
+            options: [
+                { value: 'npm', label: 'NPM package' },
+                { value: 'git', label: 'Git repository' },
+                { value: 'docker', label: 'Docker image' },
+            ],
+            yesInitialValue: 'docker',
+            initialValue: 'docker',
+            required: true,
+        },
+        version: {
+            type: 'text',
+            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',
+            initialValue: 'alpha',
+            yesInitialValue: 'alpha',
+            required: true,
+        },
+        dockerRegistry: {
+            type: 'text',
+            message: 'Which Docker image would you like to use?',
+            placeholder: DEFAULT_DOCKER_REGISTRY,
+            initialValue: (values) => defaultDockerRegistryForLang(values.lang),
+            yesInitialValue: DEFAULT_DOCKER_REGISTRY,
+            required: true,
+            hidden: (values) => values.source !== 'docker',
+        },
+        dockerPlatform: {
+            type: 'select',
+            message: 'Which Docker image platform should be used?',
+            options: [
+                { value: 'auto', label: 'Auto', hint: 'Use Docker default for this machine' },
+                { value: 'linux/amd64', label: 'linux/amd64' },
+                { value: 'linux/arm64', label: 'linux/arm64' },
+            ],
+            initialValue: DEFAULT_DOCKER_PLATFORM,
+            yesInitialValue: DEFAULT_DOCKER_PLATFORM,
+            required: true,
+            hidden: (values) => values.source !== 'docker',
+        },
+        dockerSave: {
+            type: 'boolean',
+            message: 'Save the Docker image as a tar file',
+            initialValue: false,
+            hidden: (values) => values.source !== 'docker',
+        },
+        gitUrl: {
+            type: 'text',
+            message: 'Git repository URL',
+            placeholder: 'https://github.com/nocobase/nocobase.git',
+            initialValue: 'https://github.com/nocobase/nocobase.git',
+            yesInitialValue: 'https://github.com/nocobase/nocobase.git',
+            required: true,
+            hidden: (values) => values.source !== 'git',
+        },
+        outputDir: {
+            type: 'text',
+            message: 'Download location',
+            placeholder: 'e.g. ./nocobase-latest',
+            initialValue: (values) => defaultOutputDirForVersion(String(values.version ?? 'latest').trim() || 'latest'),
+            required: true,
+            hidden: (values) => {
+                const s = values.source;
+                if (s === 'npm' || s === 'git') {
+                    return false;
+                }
+                if (s === 'docker') {
+                    return !values.dockerSave;
+                }
+                return true;
+            },
+        },
+        npmRegistry: {
+            type: 'text',
+            message: 'NPM registry URL (optional)',
+            placeholder: 'Leave empty to use the default registry',
+            initialValue: '',
+            hidden: (values) => values.source !== 'npm' && values.source !== 'git',
+        },
+        replace: {
+            type: 'boolean',
+            message: 'Clear the app directory if it already contains files',
+            initialValue: false,
+            hidden: (values) => Download.hideOutputDirAndReplaceSteps(values),
+        },
+        devDependencies: {
+            type: 'boolean',
+            message: 'Install development dependencies (npm only)',
+            initialValue: false,
+            hidden: (values) => values.source !== 'npm',
+        },
+        build: {
+            type: 'boolean',
+            message: 'Build the app after download',
+            initialValue: true,
+            yesInitialValue: true,
+            hidden: () => true,
+        },
+        buildDts: {
+            type: 'boolean',
+            message: 'Generate TypeScript declaration files',
+            initialValue: false,
+            hidden: (values) => values.source !== 'git',
+        },
     };
+    /** When true, `outputDir` / `replace` prompts are skipped (same condition for both). */
+    static hideOutputDirAndReplaceSteps(values) {
+        const s = values.source;
+        if (s === 'npm' || s === 'git') {
+            return false;
+        }
+        if (s === 'docker') {
+            return !values.dockerSave;
+        }
+        return true;
+    }
     resolveOutputDir(flags) {
         const explicit = flags['output-dir'];
         if (explicit) {
             return explicit;
         }
-        const tag = flags.version || 'latest';
-        const safe = tag.replace(/[/\\]/g, '-');
-        return `./nocobase-${safe}`;
+        return defaultOutputDirForVersion(flags.version || 'latest');
     }
-    defaultOutputDir(versionTag) {
-        const safe = versionTag.replace(/[/\\]/g, '-');
-        return `./nocobase-${safe}`;
+    async ensureOutputDirAvailable(outputDir, replace) {
+        const outputAbs = path.resolve(process.cwd(), outputDir);
+        if (replace) {
+            await fsp.rm(outputAbs, { recursive: true, force: true });
+            return outputAbs;
+        }
+        if (await pathExists(outputAbs)) {
+            this.error(`Download target already exists: ${outputDir}. Use --replace to remove it before continuing.`);
+        }
+        return outputAbs;
+    }
+    dockerTarPath(flags, outputAbs) {
+        const image = flags['docker-registry'] ?? DEFAULT_DOCKER_REGISTRY;
+        const tag = flags.version ?? 'latest';
+        const safeBase = `${image.replace(/[/:]/g, '-')}-${tag.replace(/[/\\]/g, '-')}`;
+        return path.join(outputAbs, `${safeBase}.tar`);
     }
     /**
-     * When stdin/stdout are TTY and not `-y`, prompt for any missing download options.
+     * Defaults for prompts only. Keys present in **`preset`** are omitted so `runPromptCatalog` uses
+     * **`values`** (preset) alone for those steps — no duplicate prefill for skipped prompts.
      */
-    async resolveDownloadFlags(flags) {
-        const interactive = Boolean(stdinStream.isTTY && stdoutStream.isTTY && !flags.yes);
-        let source = flags.source?.trim();
-        if (source === '') {
-            source = undefined;
-        }
-        let version = flags.version?.trim() || undefined;
-        let replace = flags.replace;
-        let dev = flags['dev'];
-        let outputDir = flags['output-dir']?.trim() || undefined;
-        if (outputDir === '') {
-            outputDir = undefined;
-        }
-        let gitUrl = flags['git-url']?.trim() || undefined;
-        if (gitUrl === '') {
-            gitUrl = undefined;
-        }
-        let dockerRegistry = flags['docker-registry']?.trim() || undefined;
-        if (dockerRegistry === '') {
-            dockerRegistry = undefined;
-        }
-        if (!interactive) {
-            if (!source) {
-                this.error('Distribution is required (--source npm|git|docker). Use a terminal for interactive setup, or pass -s/--source.');
-            }
-            const v = version || 'latest';
-            return {
-                source,
-                version: v,
-                replace,
-                'dev': dev,
-                'output-dir': outputDir,
-                'git-url': gitUrl,
-                'docker-registry': dockerRegistry,
-            };
-        }
-        p.intro('nb download');
-        if (!source) {
-            const src = await p.select({
-                message: 'How do you want to get NocoBase?',
-                options: [
-                    { value: 'npm', label: 'npm — create-nocobase-app' },
-                    { value: 'git', label: 'git — shallow clone' },
-                    { value: 'docker', label: 'docker — pull image' },
-                ],
-                initialValue: 'npm',
-            });
-            if (p.isCancel(src)) {
-                p.cancel('Download cancelled.');
-                this.exit(0);
-            }
-            source = src;
+    buildInitialValuesFromParsed(flags, preset) {
+        const initialValues = {};
+        const source = flags.source?.trim();
+        if (source) {
+            initialValues.source = source;
         }
-        if (version === undefined) {
-            const verAns = await p.text({
-                message: 'Version / dist-tag / image tag / branch alias (-v)',
-                placeholder: 'latest',
-                initialValue: 'latest',
-            });
-            if (p.isCancel(verAns)) {
-                p.cancel('Download cancelled.');
-                this.exit(0);
-            }
-            version = verAns.trim() || 'latest';
-        }
-        const versionResolved = version || 'latest';
-        if (source === 'docker') {
-            if (dockerRegistry === undefined) {
-                const reg = await p.text({
-                    message: 'Docker image without tag (--docker-registry)',
-                    placeholder: 'nocobase/nocobase',
-                    initialValue: 'nocobase/nocobase',
-                });
-                if (p.isCancel(reg)) {
-                    p.cancel('Download cancelled.');
-                    this.exit(0);
-                }
-                dockerRegistry = reg.trim() || 'nocobase/nocobase';
-            }
+        if (flags.version !== undefined) {
+            initialValues.version = flags.version.trim() || 'latest';
         }
-        if (source === 'git') {
-            if (gitUrl === undefined) {
-                const urlAns = await p.text({
-                    message: 'Git remote URL (--git-url)',
-                    placeholder: 'https://github.com/nocobase/nocobase.git',
-                    initialValue: 'https://github.com/nocobase/nocobase.git',
-                });
-                if (p.isCancel(urlAns)) {
-                    p.cancel('Download cancelled.');
-                    this.exit(0);
-                }
-                gitUrl = urlAns.trim() || 'https://github.com/nocobase/nocobase.git';
+        initialValues.replace = flags.replace;
+        initialValues.devDependencies = flags['dev-dependencies'];
+        initialValues.build = flags.build;
+        initialValues.buildDts = flags['build-dts'];
+        if (flags['output-dir'] !== undefined) {
+            initialValues.outputDir = flags['output-dir']?.trim() ?? '';
+        }
+        if (flags['git-url'] !== undefined) {
+            initialValues.gitUrl = flags['git-url']?.trim() ?? '';
+        }
+        if (flags['docker-registry'] !== undefined) {
+            initialValues.dockerRegistry = String(flags['docker-registry'] ?? '').trim();
+        }
+        initialValues.dockerPlatform = normalizeDockerPlatform(flags['docker-platform']);
+        initialValues.dockerSave = flags['docker-save'];
+        if (flags['npm-registry'] !== undefined) {
+            initialValues.npmRegistry =
+                typeof flags['npm-registry'] === 'string' ? flags['npm-registry'] : '';
+        }
+        for (const key of Object.keys(preset)) {
+            if (Object.prototype.hasOwnProperty.call(initialValues, key)) {
+                delete initialValues[key];
             }
         }
-        if (source === 'npm' || source === 'git') {
-            if (outputDir === undefined) {
-                const initialOut = this.defaultOutputDir(versionResolved);
-                const outAns = await p.text({
-                    message: 'Output directory relative to cwd (-o)',
-                    placeholder: initialOut,
-                    initialValue: initialOut,
-                });
-                if (p.isCancel(outAns)) {
-                    p.cancel('Download cancelled.');
-                    this.exit(0);
-                }
-                outputDir = outAns.trim() || initialOut;
+        return initialValues;
+    }
+    /**
+     * Preset `values` for `runPromptCatalog`: any key here skips that prompt and fixes the result.
+     * Keys not listed are resolved interactively (TTY) or from catalog defaults / `initialValues` (non-TTY / `-y`).
+     */
+    buildPresetValuesFromFlags(flags) {
+        const preset = {};
+        const argv = process.argv.slice(2);
+        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 v = String(flags['docker-registry'] ?? '').trim();
+            if (v) {
+                preset.dockerRegistry = v;
             }
-            const replaceAns = await p.confirm({
-                message: 'Delete existing output directory if present, then retry? (--replace)',
-                initialValue: replace,
-            });
-            if (p.isCancel(replaceAns)) {
-                p.cancel('Download cancelled.');
-                this.exit(0);
+        }
+        if (argvHasToken(argv, ['--docker-platform'])) {
+            preset.dockerPlatform = normalizeDockerPlatform(flags['docker-platform']);
+        }
+        if (flags['output-dir'] !== undefined) {
+            const v = flags['output-dir']?.trim();
+            if (v) {
+                preset.outputDir = v;
             }
-            replace = replaceAns;
         }
-        if (source === 'npm') {
-            const devAns = await p.confirm({
-                message: 'Install devDependencies and run a non-production yarn install? (--dev)',
-                initialValue: dev,
-            });
-            if (p.isCancel(devAns)) {
-                p.cancel('Download cancelled.');
-                this.exit(0);
+        if (flags['git-url'] !== undefined) {
+            const v = flags['git-url']?.trim();
+            if (v) {
+                preset.gitUrl = v;
             }
-            dev = devAns;
         }
+        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'];
+        }
+        return preset;
+    }
+    resolveEffectiveBuild(source, results, flags) {
+        if (source === 'npm' && !Boolean(results.devDependencies)) {
+            return false;
+        }
+        if (source === 'npm' || source === 'git') {
+            return results.build !== undefined ? Boolean(results.build) : flags.build;
+        }
+        return flags.build;
+    }
+    mapCatalogResultsToResolved(results, flags) {
+        const source = String(results.source);
+        const version = String(results.version ?? '').trim() || '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'];
+        const outputDir = results.outputDir !== undefined
+            ? String(results.outputDir).trim() || undefined
+            : flags['output-dir']?.trim() || undefined;
+        const replace = results.replace !== undefined ? Boolean(results.replace) : flags.replace;
+        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 dockerPlatform = source === 'docker'
+            ? normalizeDockerPlatform(results.dockerPlatform !== undefined
+                ? results.dockerPlatform
+                : flags['docker-platform'])
+            : undefined;
+        const dockerSave = source === 'docker'
+            ? results.dockerSave !== undefined
+                ? Boolean(results.dockerSave)
+                : flags['docker-save']
+            : false;
+        const npmRegistryRaw = results.npmRegistry !== undefined
+            ? String(results.npmRegistry)
+            : flags['npm-registry'] ?? '';
+        const npmRegistry = npmRegistryRaw.trim() || undefined;
         return {
             source,
-            version: versionResolved,
+            version,
             replace,
-            'dev': dev,
+            ...(source === 'npm' ? { 'dev-dependencies': devDependencies } : {}),
+            'build': effectiveBuild,
+            'build-dts': normalizeBuildDts(source, effectiveBuild, buildDtsWant),
             'output-dir': outputDir,
             'git-url': gitUrl,
             'docker-registry': dockerRegistry,
+            ...(source === 'docker' ? { 'docker-platform': dockerPlatform } : {}),
+            ...(source === 'docker' ? { 'docker-save': dockerSave } : {}),
+            ...(npmRegistry ? { 'npm-registry': npmRegistry } : {}),
         };
     }
+    async resolveDownloadFlags(flags) {
+        const nonInteractive = !stdinStream.isTTY || !stdoutStream.isTTY || flags.yes;
+        if (nonInteractive && !flags.source?.trim()) {
+            this.error('Download source is required in non-interactive mode. Use --source npm, --source git, or --source docker.');
+        }
+        const presetValues = this.buildPresetValuesFromFlags(flags);
+        const initialValues = this.buildInitialValuesFromParsed(flags, presetValues);
+        const results = await runPromptCatalog(Download.prompts, {
+            initialValues,
+            values: presetValues,
+            yes: flags.yes,
+            command: this,
+            hooks: {
+                onCancel: () => {
+                    p.cancel('Download cancelled.');
+                    this.exit(0);
+                },
+                onMissingNonInteractive: (message) => {
+                    this.error(message);
+                },
+            },
+        });
+        const source = String(results.source ?? '').trim();
+        if (!source || !['docker', 'npm', 'git'].includes(source)) {
+            this.error('Download source is required. Choose npm, git, or docker.');
+        }
+        if (flags['docker-save'] && source !== 'docker') {
+            this.error('--docker-save is only available when --source docker is selected.');
+        }
+        return this.mapCatalogResultsToResolved(results, flags);
+    }
+    npmRegistryUrl(flags) {
+        const url = flags['npm-registry']?.trim();
+        return url || undefined;
+    }
+    npmRegistryEnv(flags) {
+        const url = this.npmRegistryUrl(flags);
+        if (!url) {
+            return undefined;
+        }
+        return { npm_config_registry: url };
+    }
+    isVerbose() {
+        const flags = this._flags;
+        return Boolean(flags?.verbose);
+    }
+    commandStdio() {
+        return this.isVerbose() ? 'inherit' : 'ignore';
+    }
+    formatCommandForLog(name, args, cwd) {
+        const quotedArgs = args.map((arg) => (/\s/.test(arg) ? JSON.stringify(arg) : arg));
+        const commandLine = [name, ...quotedArgs].join(' ');
+        return cwd ? `${commandLine} (cwd: ${cwd})` : commandLine;
+    }
+    async runExternalCommand(name, args, options) {
+        const cwd = options?.cwd;
+        printVerbose(`Running command: ${this.formatCommandForLog(name, args, cwd)}`);
+        let loadingStarted = false;
+        let loadingTimer;
+        let updateTimer;
+        let elapsedSeconds = 0;
+        if (!this.isVerbose() && options?.loadingMessage) {
+            loadingTimer = setTimeout(() => {
+                loadingStarted = true;
+                elapsedSeconds = Math.floor(EXTERNAL_COMMAND_LOADING_DELAY_MS / 1000);
+                startTask(`${options.loadingMessage}. Please wait...`);
+                updateTimer = setInterval(() => {
+                    elapsedSeconds += Math.floor(EXTERNAL_COMMAND_LOADING_UPDATE_MS / 1000);
+                    updateTask(`${options.loadingMessage}. Still working... (${elapsedSeconds}s elapsed)`);
+                }, EXTERNAL_COMMAND_LOADING_UPDATE_MS);
+            }, EXTERNAL_COMMAND_LOADING_DELAY_MS);
+        }
+        try {
+            await run(name, args, {
+                ...options,
+                stdio: this.commandStdio(),
+            });
+        }
+        finally {
+            if (loadingTimer) {
+                clearTimeout(loadingTimer);
+            }
+            if (updateTimer) {
+                clearInterval(updateTimer);
+            }
+            if (loadingStarted) {
+                stopTask();
+            }
+        }
+    }
+    startPreparationTask(message) {
+        if (this.isVerbose()) {
+            p.log.step(message);
+            return;
+        }
+        this.preparationTaskActive = true;
+        startTask(message);
+    }
+    finishPreparationTask() {
+        if (!this.preparationTaskActive) {
+            return;
+        }
+        this.preparationTaskActive = false;
+        stopTask();
+    }
+    runOptionsWithCwd(cwd, registryEnv) {
+        if (registryEnv) {
+            return { cwd, env: registryEnv };
+        }
+        return { cwd };
+    }
+    buildCommandArgv(projectRoot, flags) {
+        const argv = ['--cwd', projectRoot];
+        if (!flags['build-dts']) {
+            argv.push('--no-dts');
+        }
+        return argv;
+    }
     async downloadFromDocker(flags) {
-        const image = flags['docker-registry'] ?? 'nocobase/nocobase';
+        const image = flags['docker-registry'] ?? DEFAULT_DOCKER_REGISTRY;
         const tag = flags.version ?? 'latest';
-        await run('docker', ['pull', `${image}:${tag}`]);
+        const imageRef = `${image}:${tag}`;
+        const platform = dockerPlatformArg(flags['docker-platform']);
+        const pullArgs = ['pull'];
+        if (platform) {
+            pullArgs.push('--platform', platform);
+        }
+        pullArgs.push(imageRef);
+        this.finishPreparationTask();
+        p.log.step(`Pulling Docker image ${imageRef}`);
+        await this.runExternalCommand('docker', pullArgs, {
+            errorName: 'docker pull',
+            loadingMessage: 'Pulling the Docker image',
+        });
+        p.log.info(`Docker image is ready: ${imageRef}`);
+        if (!flags['docker-save']) {
+            return;
+        }
+        const outputDir = this.resolveOutputDir(flags);
+        const outAbs = flags.replace
+            ? path.resolve(process.cwd(), outputDir)
+            : await this.ensureOutputDirAvailable(outputDir, false);
+        if (flags.replace) {
+            await fsp.rm(outAbs, { recursive: true, force: true });
+        }
+        await fsp.mkdir(outAbs, { recursive: true });
+        const tarPath = this.dockerTarPath(flags, outAbs);
+        p.log.step(`Saving Docker image tarball to ${tarPath}`);
+        await this.runExternalCommand('docker', ['save', '-o', tarPath, imageRef], {
+            errorName: 'docker save',
+            loadingMessage: 'Saving the Docker image tarball',
+        });
+        p.log.info(`Docker image tarball saved: ${tarPath}`);
     }
     async downloadFromNpm(flags) {
         const versionSpec = flags.version || 'latest';
         const outputDir = this.resolveOutputDir(flags);
         const projectRoot = path.resolve(process.cwd(), outputDir);
-        const npxArgs = ['-y', `create-nocobase-app@${versionSpec}`, outputDir];
-        if (!flags['dev']) {
+        await this.ensureOutputDirAvailable(outputDir, flags.replace);
+        const parentDir = path.dirname(projectRoot);
+        const appName = path.basename(projectRoot);
+        const npxArgs = ['-y', `create-nocobase-app@${versionSpec}`, appName];
+        if (!flags['dev-dependencies']) {
             npxArgs.push('--skip-dev-dependencies');
         }
-        if (flags.replace) {
-            await fsp.rm(projectRoot, { recursive: true, force: true });
-        }
-        await run('npx', npxArgs);
+        await fsp.mkdir(parentDir, { recursive: true });
+        const registryEnv = this.npmRegistryEnv(flags);
+        this.finishPreparationTask();
+        p.log.step(`Creating NocoBase app "${appName}" from npm`);
+        await this.runExternalCommand('npx', npxArgs, {
+            ...this.runOptionsWithCwd(parentDir, registryEnv),
+            errorName: 'npx create-nocobase-app',
+            loadingMessage: 'Creating the app scaffold',
+        });
         const installArgs = ['install'];
-        if (!flags['dev']) {
+        if (!flags['dev-dependencies']) {
             installArgs.push('--production');
         }
-        await run('yarn', installArgs, { cwd: projectRoot });
+        p.log.step(`Installing dependencies in ${projectRoot}`);
+        await this.runExternalCommand('yarn', installArgs, {
+            ...this.runOptionsWithCwd(projectRoot, registryEnv),
+            errorName: 'yarn install',
+            loadingMessage: 'Installing dependencies',
+        });
+        if (flags.build && flags['dev-dependencies']) {
+            p.log.step(`Building app in ${projectRoot}`);
+            await this.config.runCommand('build', [
+                ...this.buildCommandArgv(projectRoot, flags),
+                ...(this.isVerbose() ? ['--verbose'] : []),
+            ]);
+        }
+        p.log.info(`NocoBase app is ready at ${projectRoot}`);
         return projectRoot;
     }
     async downloadFromGit(flags) {
         const repoUrl = flags['git-url'] ?? 'https://github.com/nocobase/nocobase.git';
         const versionSpec = flags.version || 'latest';
         const outputDir = this.resolveOutputDir(flags);
-        const versionToRef = {
-            'latest': 'main',
-            'beta': 'next',
-            'alpha': 'develop',
-        };
-        if (flags.replace) {
-            await fsp.rm(path.resolve(process.cwd(), outputDir), { recursive: true, force: true });
-        }
-        const branch = versionToRef[versionSpec] || versionSpec;
+        await this.ensureOutputDirAvailable(outputDir, flags.replace);
+        const branch = gitRefForVersion(versionSpec);
         const gitArgs = ['clone'];
         gitArgs.push('--branch', branch);
         gitArgs.push('--depth', '1', repoUrl, outputDir);
-        await run('git', gitArgs);
+        this.finishPreparationTask();
+        p.log.step(branch === versionSpec
+            ? `Cloning NocoBase from ${repoUrl} (${branch})`
+            : `Cloning NocoBase from ${repoUrl} (${branch}, resolved from ${versionSpec})`);
+        await this.runExternalCommand('git', gitArgs, {
+            errorName: 'git clone',
+            loadingMessage: 'Cloning the repository',
+        });
         const projectRoot = path.resolve(process.cwd(), outputDir);
-        await run('yarn', ['install'], { cwd: projectRoot });
+        const registryEnv = this.npmRegistryEnv(flags);
+        p.log.step(`Installing dependencies in ${projectRoot}`);
+        await this.runExternalCommand('yarn', ['install'], {
+            ...this.runOptionsWithCwd(projectRoot, registryEnv),
+            errorName: 'yarn install',
+            loadingMessage: 'Installing dependencies',
+        });
+        if (flags.build) {
+            p.log.step(`Building app in ${projectRoot}`);
+            await this.config.runCommand('build', [
+                ...this.buildCommandArgv(projectRoot, flags),
+                ...(this.isVerbose() ? ['--verbose'] : []),
+            ]);
+        }
+        p.log.info(`NocoBase app is ready at ${projectRoot}`);
         return projectRoot;
     }
-    /**
-     * @returns Final resolved flags and, for npm/git, the absolute project directory.
-     */
     async download() {
         const { flags } = await this.parse(Download);
+        this._flags = flags;
+        setVerboseMode(Boolean(flags.verbose));
+        if (!flags['no-intro']) {
+            p.intro('Get NocoBase');
+        }
         const resolved = await this.resolveDownloadFlags(flags);
-        switch (resolved.source) {
-            case 'npm': {
-                const projectRoot = await this.downloadFromNpm(resolved);
-                return { resolved, projectRoot };
-            }
-            case 'docker': {
-                await this.downloadFromDocker(resolved);
-                return { resolved, projectRoot: undefined };
-            }
-            case 'git': {
-                const projectRoot = await this.downloadFromGit(resolved);
-                return { resolved, projectRoot };
+        const source = resolved.source;
+        this.startPreparationTask(`Preparing download from ${downloadSourceLabel(source)}`);
+        try {
+            switch (source) {
+                case 'npm': {
+                    const projectRoot = await this.downloadFromNpm(resolved);
+                    return { resolved, projectRoot };
+                }
+                case 'docker': {
+                    await this.downloadFromDocker(resolved);
+                    return { resolved, projectRoot: undefined };
+                }
+                case 'git': {
+                    const projectRoot = await this.downloadFromGit(resolved);
+                    return { resolved, projectRoot };
+                }
+                default:
+                    this.error(`Unsupported download source: ${resolved.source}`);
             }
-            default:
-                this.error(`Invalid --source: ${resolved.source}`);
+        }
+        finally {
+            this.finishPreparationTask();
         }
     }
     async run() {
         try {
-            return await this.download();
+            const result = await this.download();
+            p.outro(`Download completed via ${downloadSourceLabel(result.resolved.source)}.`);
+            return result;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);