@nocobase/cli 2.1.0-alpha.4 → 2.1.0-alpha.40

package/dist/commands/backup/create.js

@@ -0,0 +1,147 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * 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 { Command, Flags } from '@oclif/core';
+import { BACKUP_CREATE_TIMEOUT_MS, BACKUP_POLL_INTERVAL_MS, BACKUP_RUNTIME_COMMANDS, buildBackupEnvArgv, ensureBackupRuntimeCommands, resolveBackupCreateOutputPath, resolveBackupTargetEnv, runBackupCliJsonCommand, sleep, } from '../../lib/backup.js';
+import { ensureCrossEnvConfirmed, hasExplicitEnvSelection } from '../../lib/env-guard.js';
+import { announceTargetEnv, failTask, startTask, succeedTask, updateTask } from '../../lib/ui.js';
+function formatBackupCreateTimeoutError(envName, name) {
+    return [
+        `Backup "${name}" did not finish in time for "${envName}".`,
+        `Waited ${Math.floor(BACKUP_CREATE_TIMEOUT_MS / 1000)}s but it still reports \`inProgress: true\`.`,
+    ].join(' ');
+}
+function readBackupCreateResult(response) {
+    const name = String(response.data?.name ?? '').trim();
+    if (!name) {
+        throw new Error('Backup creation did not return a backup name.');
+    }
+    return {
+        name,
+        inProgress: Boolean(response.data?.inProgress),
+    };
+}
+function readBackupInProgress(response, name) {
+    const status = response.data?.[name];
+    if (!status || typeof status !== 'object') {
+        throw new Error(`Backup status did not include "${name}".`);
+    }
+    return Boolean(status.inProgress);
+}
+function readDownloadOutput(response) {
+    const output = String(response.data?.output ?? '').trim();
+    return output || undefined;
+}
+export default class BackupCreate extends Command {
+    static summary = 'Create a backup through the selected env and download it locally';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> --output ./fixtures/base.nbdump',
+        '<%= config.bin %> <%= command.id %> --env e2e --output ./fixtures',
+    ];
+    static flags = {
+        env: Flags.string({
+            char: 'e',
+            description: 'CLI env name to back up. Defaults to the current env when omitted',
+        }),
+        yes: Flags.boolean({
+            char: 'y',
+            description: 'Confirm using --env when it targets a different env than the current env',
+            default: false,
+        }),
+        output: Flags.string({
+            char: 'o',
+            description: 'Download path. When omitted, save to the current directory using the remote backup filename',
+        }),
+        'json-output': Flags.boolean({
+            char: 'j',
+            description: 'Print the final backup result as JSON',
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(BackupCreate);
+        const requestedEnv = flags.env?.trim() || undefined;
+        const explicitEnvSelection = Boolean(requestedEnv && hasExplicitEnvSelection(this.argv));
+        const jsonOutput = Boolean(flags['json-output']);
+        if (explicitEnvSelection) {
+            const confirmed = await ensureCrossEnvConfirmed({
+                command: this,
+                requestedEnv,
+                yes: flags.yes,
+            });
+            if (!confirmed) {
+                return;
+            }
+        }
+        const { envName, env } = await resolveBackupTargetEnv(requestedEnv);
+        const envArgv = buildBackupEnvArgv({
+            requestedEnv,
+            explicitEnvSelection,
+            yes: flags.yes,
+        });
+        if (!jsonOutput) {
+            announceTargetEnv(envName);
+        }
+        await ensureBackupRuntimeCommands({
+            envName,
+            env,
+            commandIds: [
+                BACKUP_RUNTIME_COMMANDS.create,
+                BACKUP_RUNTIME_COMMANDS.status,
+                BACKUP_RUNTIME_COMMANDS.download,
+            ],
+            quiet: jsonOutput,
+        });
+        try {
+            if (!jsonOutput) {
+                startTask(`Creating backup for "${envName}"...`);
+            }
+            const createResponse = await runBackupCliJsonCommand(['api', 'backup', 'create', ...envArgv], { errorName: 'nb api backup create' });
+            const { name, inProgress } = readBackupCreateResult(createResponse);
+            const outputPath = await resolveBackupCreateOutputPath(flags.output, name);
+            const startedAt = Date.now();
+            let pending = inProgress;
+            while (pending) {
+                const now = Date.now();
+                const elapsedMs = now - startedAt;
+                if (elapsedMs >= BACKUP_CREATE_TIMEOUT_MS) {
+                    throw new Error(formatBackupCreateTimeoutError(envName, name));
+                }
+                const elapsedSeconds = Math.max(1, Math.floor(elapsedMs / 1000));
+                if (!jsonOutput) {
+                    updateTask(`Waiting for backup "${name}" to finish for "${envName}"... (${elapsedSeconds}s elapsed)`);
+                }
+                await sleep(BACKUP_POLL_INTERVAL_MS);
+                const statusResponse = await runBackupCliJsonCommand(['api', 'backup', 'status', '--name', name, ...envArgv], { errorName: 'nb api backup status' });
+                pending = readBackupInProgress(statusResponse, name);
+            }
+            if (!jsonOutput) {
+                updateTask(`Downloading backup "${name}" for "${envName}"...`);
+            }
+            const downloadResponse = await runBackupCliJsonCommand(['api', 'backup', 'download', '--name', name, '--output', outputPath, ...envArgv], { errorName: 'nb api backup download' });
+            const savedPath = readDownloadOutput(downloadResponse) ?? outputPath;
+            const result = {
+                env: envName,
+                name,
+                output: savedPath,
+            };
+            if (jsonOutput) {
+                this.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            succeedTask(`Backup saved to ${savedPath}`);
+        }
+        catch (error) {
+            if (!jsonOutput) {
+                failTask(`Failed to create backup for "${envName}".`);
+            }
+            throw error;
+        }
+    }
+}

package/dist/commands/backup/index.js

@@ -0,0 +1,20 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * 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 { Command, loadHelpClass } from '@oclif/core';
+export default class Backup extends Command {
+    static summary = 'Create or restore NocoBase backups';
+    async run() {
+        await this.parse(Backup);
+        const Help = await loadHelpClass(this.config);
+        await new Help(this.config, this.config.pjson.oclif.helpOptions ?? this.config.pjson.helpOptions).showHelp([
+            this.id ?? 'backup',
+            ...this.argv,
+        ]);
+    }
+}

package/dist/commands/backup/restore.js

@@ -0,0 +1,105 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * 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 { Command, Flags } from '@oclif/core';
+import { BACKUP_RUNTIME_COMMANDS, buildBackupEnvArgv, ensureBackupRuntimeCommands, resolveBackupRestoreFilePath, resolveBackupTargetEnv, resolveBackupWaitApiBaseUrl, runBackupCliCommand, } from '../../lib/backup.js';
+import { waitForAppReady } from '../../lib/app-health.js';
+import { ensureCrossEnvConfirmed, hasExplicitEnvSelection } from '../../lib/env-guard.js';
+import { confirm } from "../../lib/inquirer.js";
+import { announceTargetEnv, failTask, isInteractiveTerminal, startTask, stopTask, succeedTask } from '../../lib/ui.js';
+async function confirmBackupRestore(envName, filePath, force) {
+    if (force) {
+        return true;
+    }
+    if (!isInteractiveTerminal()) {
+        throw new Error(`\`nb backup restore\` needs confirmation. Re-run with \`--force\` to restore ${filePath} into "${envName}" in non-interactive mode.`);
+    }
+    try {
+        return await confirm({
+            message: `Restore backup "${filePath}" into "${envName}"? This will overwrite application data.`,
+            default: false,
+        });
+    }
+    catch {
+        return false;
+    }
+}
+export default class BackupRestore extends Command {
+    static summary = 'Restore a backup file into the selected env';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --file ./fixtures/base.nbdump --force',
+        '<%= config.bin %> <%= command.id %> --env e2e --file ./fixtures/base.nbdump --yes --force',
+    ];
+    static flags = {
+        env: Flags.string({
+            char: 'e',
+            description: 'CLI env name to restore into. Defaults to the current env when omitted',
+        }),
+        yes: Flags.boolean({
+            char: 'y',
+            description: 'Confirm using --env when it targets a different env than the current env',
+            default: false,
+        }),
+        file: Flags.string({
+            char: 'f',
+            description: 'Local backup file to upload and restore',
+            required: true,
+        }),
+        force: Flags.boolean({
+            description: 'Confirm overwriting application data during restore',
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(BackupRestore);
+        const requestedEnv = flags.env?.trim() || undefined;
+        const explicitEnvSelection = Boolean(requestedEnv && hasExplicitEnvSelection(this.argv));
+        if (explicitEnvSelection) {
+            const confirmed = await ensureCrossEnvConfirmed({
+                command: this,
+                requestedEnv,
+                yes: flags.yes,
+            });
+            if (!confirmed) {
+                return;
+            }
+        }
+        const filePath = await resolveBackupRestoreFilePath(flags.file);
+        const { envName, env } = await resolveBackupTargetEnv(requestedEnv);
+        const restoreConfirmed = await confirmBackupRestore(envName, filePath, flags.force);
+        if (!restoreConfirmed) {
+            return;
+        }
+        const envArgv = buildBackupEnvArgv({
+            requestedEnv,
+            explicitEnvSelection,
+            yes: flags.yes,
+        });
+        announceTargetEnv(envName);
+        await ensureBackupRuntimeCommands({
+            envName,
+            env,
+            commandIds: [BACKUP_RUNTIME_COMMANDS.restoreUpload],
+        });
+        startTask(`Restoring backup for "${envName}" from ${filePath}...`);
+        try {
+            await runBackupCliCommand(['api', 'backup', 'restore-upload', '--file', filePath, '--force', ...envArgv], { errorName: 'nb api backup restore-upload' });
+            stopTask();
+            await waitForAppReady({
+                envName,
+                apiBaseUrl: resolveBackupWaitApiBaseUrl(env),
+            });
+            succeedTask(`Backup restored for "${envName}" from ${filePath}`);
+        }
+        catch (error) {
+            stopTask();
+            failTask(`Failed to restore backup for "${envName}".`);
+            throw error;
+        }
+    }
+}

package/{src/cli.js → dist/commands/build.js}

@@ -6,14 +6,7 @@
  * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
-
-const { Command } = require('commander');
-const commands = require('./commands');
-
-const cli = new Command();
-
-cli.version(require('../package.json').version);
-
-commands(cli);
-
-module.exports = cli;
+import SourceBuild from './source/build.js';
+export default class Build extends SourceBuild {
+    static hidden = true;
+}

package/dist/commands/config/delete.js

@@ -0,0 +1,30 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * 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 { Args, Command } from '@oclif/core';
+import { assertSupportedCliConfigKey, deleteCliConfigValue } from '../../lib/cli-config.js';
+export default class ConfigDelete extends Command {
+    static summary = 'Delete an explicitly configured CLI setting';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> license.pkg-url',
+        '<%= config.bin %> <%= command.id %> docker.network',
+        '<%= config.bin %> <%= command.id %> docker.container-prefix',
+    ];
+    static args = {
+        key: Args.string({
+            description: 'Configuration key',
+            required: true,
+        }),
+    };
+    async run() {
+        const { args } = await this.parse(ConfigDelete);
+        const key = assertSupportedCliConfigKey(args.key);
+        const removed = await deleteCliConfigValue(key);
+        this.log(removed ? `Deleted ${key}` : `${key} was not set`);
+    }
+}

package/dist/commands/config/get.js

@@ -0,0 +1,29 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * 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 { Args, Command } from '@oclif/core';
+import { assertSupportedCliConfigKey, getCliConfigValue } from '../../lib/cli-config.js';
+export default class ConfigGet extends Command {
+    static summary = 'Get the effective CLI configuration value for a key';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> license.pkg-url',
+        '<%= config.bin %> <%= command.id %> docker.network',
+        '<%= config.bin %> <%= command.id %> docker.container-prefix',
+    ];
+    static args = {
+        key: Args.string({
+            description: 'Configuration key',
+            required: true,
+        }),
+    };
+    async run() {
+        const { args } = await this.parse(ConfigGet);
+        const key = assertSupportedCliConfigKey(args.key);
+        this.log(await getCliConfigValue(key));
+    }
+}

package/dist/commands/config/index.js

@@ -0,0 +1,20 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * 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 { Command, loadHelpClass } from '@oclif/core';
+export default class Config extends Command {
+    static summary = 'Manage CLI configuration defaults';
+    async run() {
+        await this.parse(Config);
+        const Help = await loadHelpClass(this.config);
+        await new Help(this.config, this.config.pjson.oclif.helpOptions ?? this.config.pjson.helpOptions).showHelp([
+            this.id ?? 'config',
+            ...this.argv,
+        ]);
+    }
+}

package/dist/commands/config/list.js

@@ -0,0 +1,29 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * 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 { Command } from '@oclif/core';
+import { listExplicitCliConfigValues, SUPPORTED_CLI_CONFIG_KEYS } from '../../lib/cli-config.js';
+import { renderTable } from '../../lib/ui.js';
+export default class ConfigList extends Command {
+    static summary = 'List explicitly configured CLI settings';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+    ];
+    async run() {
+        await this.parse(ConfigList);
+        const values = await listExplicitCliConfigValues();
+        const rows = SUPPORTED_CLI_CONFIG_KEYS
+            .filter((key) => Boolean(values[key]))
+            .map((key) => [key, values[key] ?? '']);
+        if (!rows.length) {
+            this.log('No CLI config values are set.');
+            return;
+        }
+        this.log(renderTable(['Key', 'Value'], rows));
+    }
+}

package/dist/commands/config/set.js

@@ -0,0 +1,35 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * 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 { Args, Command } from '@oclif/core';
+import { assertSupportedCliConfigKey, setCliConfigValue } from '../../lib/cli-config.js';
+export default class ConfigSet extends Command {
+    static summary = 'Set a CLI configuration value';
+    static description = 'Set a supported CLI configuration key. Supported keys: license.pkg-url, docker.network, docker.container-prefix.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> license.pkg-url https://pkg.nocobase.com/',
+        '<%= config.bin %> <%= command.id %> docker.network nocobase',
+        '<%= config.bin %> <%= command.id %> docker.container-prefix nb',
+    ];
+    static args = {
+        key: Args.string({
+            description: 'Configuration key',
+            required: true,
+        }),
+        value: Args.string({
+            description: 'Configuration value',
+            required: true,
+        }),
+    };
+    async run() {
+        const { args } = await this.parse(ConfigSet);
+        const key = assertSupportedCliConfigKey(args.key);
+        const value = await setCliConfigValue(key, args.value);
+        this.log(`${key}=${value}`);
+    }
+}

package/dist/commands/db/check.js

@@ -0,0 +1,240 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * 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 { Command, Flags } from '@oclif/core';
+import { formatMissingManagedAppEnvMessage, resolveManagedAppRuntime } from '../../lib/app-runtime.js';
+import { resolveBuiltinDbConnection } from '../../lib/builtin-db.js';
+import { checkExternalDbConnection, formatDbCheckAddress, readExternalDbConnectionConfig, } from "../../lib/db-connection-check.js";
+import { DEFAULT_DOCKER_REGISTRY, DEFAULT_DOCKER_VERSION, resolveDockerImageRef, } from "../../lib/docker-image.js";
+import { commandOutput } from '../../lib/run-npm.js';
+import { validateTcpPort } from "../../lib/prompt-validators.js";
+function trimValue(value) {
+    const text = String(value ?? '').trim();
+    return text || undefined;
+}
+function resolveRequiredDbField(flagValue, envValue) {
+    return trimValue(flagValue) ?? trimValue(envValue);
+}
+function normalizeDockerPlatform(value) {
+    const text = trimValue(value);
+    if (!text || text === 'auto') {
+        return undefined;
+    }
+    if (text === 'linux/amd64' || text === 'linux/arm64') {
+        return text;
+    }
+    return undefined;
+}
+function formatMissingFieldsMessage(missing, hasEnv) {
+    return [
+        'Missing database settings for connectivity check.',
+        `Required: ${missing.join(', ')}.`,
+        hasEnv
+            ? 'Pass `--env <name>` to reuse a saved env, or provide the missing `--db-*` flags explicitly.'
+            : 'Provide all required `--db-*` flags explicitly, or pass `--env <name>` to reuse a saved env.',
+    ].join('\n');
+}
+function resolveDbConfigFromFlags(flags, envConfig) {
+    return {
+        builtinDb: false,
+        dbDialect: resolveRequiredDbField(flags['db-dialect'], envConfig?.dbDialect),
+        dbHost: resolveRequiredDbField(flags['db-host'], envConfig?.dbHost),
+        dbPort: resolveRequiredDbField(flags['db-port'], envConfig?.dbPort),
+        dbDatabase: resolveRequiredDbField(flags['db-database'], envConfig?.dbDatabase),
+        dbUser: resolveRequiredDbField(flags['db-user'], envConfig?.dbUser),
+        dbPassword: flags['db-password'] !== undefined
+            ? String(flags['db-password'] ?? '')
+            : envConfig?.dbPassword !== undefined
+                ? String(envConfig.dbPassword ?? '')
+                : undefined,
+    };
+}
+function validateDbConfigOrThrow(command, dbConfig, hasEnv) {
+    const missing = [];
+    if (!dbConfig.dbDialect) {
+        missing.push('--db-dialect');
+    }
+    if (!dbConfig.dbHost) {
+        missing.push('--db-host');
+    }
+    if (!dbConfig.dbPort) {
+        missing.push('--db-port');
+    }
+    if (!dbConfig.dbDatabase) {
+        missing.push('--db-database');
+    }
+    if (!dbConfig.dbUser) {
+        missing.push('--db-user');
+    }
+    if (!dbConfig.dbPassword) {
+        missing.push('--db-password');
+    }
+    if (missing.length > 0) {
+        command.error(formatMissingFieldsMessage(missing, hasEnv));
+    }
+    const portError = validateTcpPort(dbConfig.dbPort);
+    if (portError) {
+        command.error(portError);
+    }
+}
+async function resolveDbCheckInput(command, flags) {
+    const envName = flags.env?.trim() || undefined;
+    if (!envName) {
+        const dbConfig = resolveDbConfigFromFlags(flags);
+        validateDbConfigOrThrow(command, dbConfig, false);
+        return {
+            dbConfig,
+        };
+    }
+    const runtime = await resolveManagedAppRuntime(envName);
+    if (!runtime) {
+        command.error(formatMissingManagedAppEnvMessage(envName));
+    }
+    const envConfig = { ...runtime.env.config };
+    if ((runtime.kind === 'local' || runtime.kind === 'docker') && runtime.env.config.builtinDb) {
+        const builtinDbConnection = await resolveBuiltinDbConnection(runtime);
+        envConfig.dbHost = builtinDbConnection.dbHost;
+        envConfig.dbPort = builtinDbConnection.dbPort;
+        envConfig.dbDialect = builtinDbConnection.dbDialect;
+    }
+    const dbConfig = resolveDbConfigFromFlags(flags, envConfig);
+    validateDbConfigOrThrow(command, dbConfig, true);
+    return {
+        envName: runtime.envName,
+        kind: runtime.kind,
+        runtime: runtime,
+        dbConfig,
+    };
+}
+function buildConnectionConfigOrThrow(command, dbConfig) {
+    const connectionConfig = readExternalDbConnectionConfig(dbConfig);
+    if (!connectionConfig) {
+        command.error('Unsupported or incomplete database settings for connectivity check.');
+    }
+    return connectionConfig;
+}
+async function runExplicitDbCheck(command, dbConfig) {
+    const connectionConfig = buildConnectionConfigOrThrow(command, dbConfig);
+    const address = formatDbCheckAddress(connectionConfig);
+    const validationError = await checkExternalDbConnection(connectionConfig);
+    return {
+        ok: !validationError,
+        dialect: connectionConfig.dialect,
+        address,
+        error: validationError ?? null,
+    };
+}
+async function runDockerDbCheck(command, runtime, dbConfig) {
+    const connectionConfig = buildConnectionConfigOrThrow(command, dbConfig);
+    const config = runtime.env.config ?? {};
+    const imageRef = resolveDockerImageRef(config.dockerRegistry, config.downloadVersion, {
+        defaultRegistry: DEFAULT_DOCKER_REGISTRY,
+        defaultVersion: DEFAULT_DOCKER_VERSION,
+    });
+    const args = [
+        'run',
+        '--rm',
+        '--network',
+        runtime.dockerNetworkName || runtime.workspaceName,
+    ];
+    const dockerPlatform = normalizeDockerPlatform(config.dockerPlatform);
+    if (dockerPlatform) {
+        args.push('--platform', dockerPlatform);
+    }
+    args.push('--entrypoint', 'nb', imageRef, 'db', 'check', '--db-dialect', connectionConfig.dialect, '--db-host', connectionConfig.host, '--db-port', String(connectionConfig.port), '--db-database', connectionConfig.database, '--db-user', connectionConfig.user, '--db-password', connectionConfig.password, '--json');
+    const output = await commandOutput('docker', args, {
+        errorName: 'docker run',
+    });
+    let payload;
+    try {
+        payload = JSON.parse(output);
+    }
+    catch {
+        command.error(`Failed to parse database check response from Docker: ${output}`);
+    }
+    const ok = Boolean(payload.ok);
+    const dialect = trimValue(payload.dialect) || connectionConfig.dialect;
+    const address = trimValue(payload.address) || formatDbCheckAddress(connectionConfig);
+    const error = trimValue(payload.error) || null;
+    return {
+        ok,
+        dialect,
+        address,
+        error,
+    };
+}
+async function runDbCheckForRuntime(command, runtime, dbConfig) {
+    if (runtime.kind === 'docker') {
+        return await runDockerDbCheck(command, runtime, dbConfig);
+    }
+    if (runtime.kind === 'local') {
+        return await runExplicitDbCheck(command, dbConfig);
+    }
+    command.error(`Env "${runtime.envName}" does not support automatic database connectivity checks.`);
+}
+export default class DbCheck extends Command {
+    static description = 'Check whether a database is reachable using the selected env settings or explicit `--db-*` flags.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --env app1',
+        '<%= config.bin %> <%= command.id %> --env app1 --db-password new-secret --json',
+        '<%= config.bin %> <%= command.id %> --db-dialect postgres --db-host 127.0.0.1 --db-port 5432 --db-database nocobase --db-user nocobase --db-password secret',
+    ];
+    static flags = {
+        env: Flags.string({
+            char: 'e',
+            description: 'CLI env name to read saved database settings from. Defaults to the current env when omitted',
+        }),
+        'db-dialect': Flags.string({
+            description: 'Database dialect: postgres, kingbase, mysql, or mariadb.',
+            options: ['postgres', 'kingbase', 'mysql', 'mariadb'],
+        }),
+        'db-host': Flags.string({
+            description: 'Database host name or IP address.',
+        }),
+        'db-port': Flags.string({
+            description: 'Database TCP port.',
+        }),
+        'db-database': Flags.string({
+            description: 'Database name.',
+        }),
+        'db-user': Flags.string({
+            description: 'Database username.',
+        }),
+        'db-password': Flags.string({
+            description: 'Database password.',
+        }),
+        json: Flags.boolean({
+            description: 'Output the check result as JSON.',
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(DbCheck);
+        const input = await resolveDbCheckInput(this, flags);
+        const result = input.runtime
+            ? await runDbCheckForRuntime(this, input.runtime, input.dbConfig)
+            : await runExplicitDbCheck(this, input.dbConfig);
+        if (flags.json) {
+            this.log(JSON.stringify({
+                ok: result.ok,
+                env: input.envName,
+                kind: input.kind,
+                dialect: result.dialect,
+                address: result.address,
+                error: result.error,
+            }, null, 2));
+            return;
+        }
+        if (!result.ok) {
+            this.error(result.error ?? 'Database check failed.');
+        }
+        this.log(input.envName
+            ? `Database check passed for env "${input.envName}" (${result.dialect} ${result.address}).`
+            : `Database check passed (${result.dialect} ${result.address}).`);
+    }
+}