@nocobase/cli 2.1.0-beta.22 → 2.1.0-beta.24

package/README.md

@@ -60,12 +60,16 @@ nb init --ui
 When creating a new app, it can also install NocoBase AI coding skills
 (`nocobase/skills`) globally.
 
+Use `--skip-skills` if the skills are managed separately, or when running in CI
+or offline environments where `nb init` should not install or update them.
+
 ### Non-Interactive Setup
 
 When prompts are skipped, an app/env name is required:
 
 ```bash
 nb init --env app1 --yes
+nb init --env app1 --yes --skip-skills
 ```
 
 Install with Docker:
@@ -111,11 +115,12 @@ If `nb init` was interrupted after the env config had already been saved, you ca
 
 ```bash
 nb init --env app1 --resume
+nb init --env app1 --resume --skip-skills
 ```
 
 `--resume` reuses the saved workspace env config for app, source, database, and env connection settings. In interactive mode, it only asks for any missing setup-only values.
 
-In non-interactive mode, pass these setup-only flags again because they are not saved in env config:
+In non-interactive resume mode, `nb init --resume --yes` uses default initialization values unless these flags are passed explicitly:
 
 - `--lang`
 - `--root-username`
@@ -128,7 +133,7 @@ In non-interactive mode, pass these setup-only flags again because they are not
 | Command | Description |
 | --- | --- |
 | `nb init` | Set up NocoBase and connect it as a CLI env for coding agents. |
-| `nb app` | Manage app runtimes: start, stop, restart, logs, status, cleanup, and upgrades. |
+| `nb app` | Manage app runtimes: start, stop, restart, logs, cleanup, and upgrades. |
 | `nb source` | Manage the local source project: download, develop, build, and test. |
 | `nb db` | Inspect or manage built-in database runtime status for local envs. |
 | `nb env` | Manage saved CLI env connections. |
@@ -137,13 +142,13 @@ In non-interactive mode, pass these setup-only flags again because they are not
 | `nb self` | Check or update the installed NocoBase CLI. |
 | `nb skills` | Check, install, or update global NocoBase AI coding skills. |
 
-Recommended style: use `--env` explicitly for app/runtime commands. `-e` is the short form:
+Recommended style: pass the env name explicitly when operating on a specific env. Runtime commands accept `--env`, and `nb env info` also accepts a positional env name:
 
 ```bash
 nb app start --env app1
 nb app restart --env app1
 nb app logs --env app1
-nb app ps --env app1
+nb env info app1
 nb db ps --env app1
 ```
 
@@ -291,12 +296,18 @@ Show the current env:
 nb env
 ```
 
-List configured envs:
+List configured envs with token-verified API status:
 
 ```bash
 nb env list
 ```
 
+Show details for one env:
+
+```bash
+nb env info app1
+```
+
 Switch the current env:
 
 ```bash

package/README.zh-CN.md

@@ -55,12 +55,15 @@ nb init --ui
 
 `nb init` 可以连接已有的 NocoBase 应用，也可以安装一个新的 NocoBase 应用。创建新应用时，还可以全局安装 NocoBase AI coding skills (`nocobase/skills`)。
 
+如果已经自行管理 skills，或在 CI、离线环境中运行，不希望 `nb init` 安装或更新 skills，可以传入 `--skip-skills`。
+
 ### 非交互式初始化
 
 跳过交互提示时，必须提供 app/env name：
 
 ```bash
 nb init --env app1 --yes
+nb init --env app1 --yes --skip-skills
 ```
 
 使用 Docker 安装：
@@ -106,11 +109,12 @@ nb init --env app1 --yes --source git --version fix/cli-v2
 
 ```bash
 nb init --env app1 --resume
+nb init --env app1 --resume --skip-skills
 ```
 
 `--resume` 会复用工作区里已保存的 env config，包括应用、source、数据库和 env 连接相关配置。在交互模式下，只会继续补齐缺失的初始化参数。
 
-在非交互模式下，需要重新传这些只用于初始化、不会保存到 env config 的参数：
+在非交互恢复模式下，如果没有显式传入这些参数，`nb init --resume --yes` 会使用默认初始化值：
 
 - `--lang`
 - `--root-username`
@@ -130,13 +134,13 @@ nb init --env app1 --resume
 | `nb api` | 通过 CLI 调用 NocoBase API 资源。 |
 | `nb plugin` | 管理选中 NocoBase env 的插件。 |
 
-推荐在应用和运行时相关命令里显式使用 `--env`；`-e` 是它的简写：
+推荐在操作指定 env 时显式传入 env 名称。运行时命令支持 `--env`，`nb env info` 也支持位置参数：
 
 ```bash
 nb app start --env app1
 nb app restart --env app1
 nb app logs --env app1
-nb app ps --env app1
+nb env info app1
 nb db ps --env app1
 ```
 
@@ -252,12 +256,18 @@ nb app down --env app1 --all --yes
 nb env
 ```
 
-查看已配置的 env：
+查看已配置的 env 及 Token 验证后的 API 状态：
 
 ```bash
 nb env list
 ```
 
+查看某个 env 的详情：
+
+```bash
+nb env info app1
+```
+
 切换当前 env：
 
 ```bash

package/dist/commands/db/check.js

@@ -0,0 +1,132 @@
+/**
+ * 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 } from '../../lib/app-runtime.js';
+import { getEnv } from '../../lib/auth-store.js';
+import { checkExternalDbConnection, formatDbCheckAddress, readExternalDbConnectionConfig, } from "../../lib/db-connection-check.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 formatMissingFieldsMessage(missing) {
+    return [
+        'Missing database settings for connectivity check.',
+        `Required: ${missing.join(', ')}.`,
+        'Pass `--env <name>` to reuse a saved env, or provide all `--db-*` flags explicitly.',
+    ].join('\n');
+}
+export default class DbCheck extends Command {
+    static description = 'Check whether the current machine can connect to a database using saved env config or explicit --db-* flags.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --env app1',
+        '<%= 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',
+        '<%= config.bin %> <%= command.id %> --env app1 --db-password new-secret --json',
+    ];
+    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 envName = flags.env?.trim() || undefined;
+        const env = envName || !flags['db-host'] ? await getEnv(envName) : undefined;
+        if (envName && !env) {
+            this.error(formatMissingManagedAppEnvMessage(envName));
+        }
+        const config = env?.config ?? {};
+        const dbConfig = {
+            builtinDb: false,
+            dbDialect: resolveRequiredDbField(flags['db-dialect'], config.dbDialect),
+            dbHost: resolveRequiredDbField(flags['db-host'], config.dbHost),
+            dbPort: resolveRequiredDbField(flags['db-port'], config.dbPort),
+            dbDatabase: resolveRequiredDbField(flags['db-database'], config.dbDatabase),
+            dbUser: resolveRequiredDbField(flags['db-user'], config.dbUser),
+            dbPassword: flags['db-password'] !== undefined
+                ? String(flags['db-password'] ?? '')
+                : String(config.dbPassword ?? ''),
+        };
+        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) {
+            this.error(formatMissingFieldsMessage(missing));
+        }
+        const portError = validateTcpPort(dbConfig.dbPort);
+        if (portError) {
+            this.error(portError);
+        }
+        const connectionConfig = readExternalDbConnectionConfig(dbConfig);
+        if (!connectionConfig) {
+            this.error('Unsupported or incomplete database settings for connectivity check.');
+        }
+        const address = formatDbCheckAddress(connectionConfig);
+        const validationError = await checkExternalDbConnection(connectionConfig);
+        if (flags.json) {
+            this.log(JSON.stringify({
+                ok: !validationError,
+                env: env?.name,
+                dialect: connectionConfig.dialect,
+                address,
+                error: validationError ?? null,
+            }, null, 2));
+            return;
+        }
+        if (validationError) {
+            this.error(validationError);
+        }
+        this.log(env?.name
+            ? `Database check passed for env "${env.name}" (${connectionConfig.dialect} ${address}).`
+            : `Database check passed (${connectionConfig.dialect} ${address}).`);
+    }
+}

package/dist/commands/{app → env}/info.js

@@ -6,7 +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.
  */
-import { Command, Flags } from '@oclif/core';
+import { Args, Command, Flags } from '@oclif/core';
 import { formatMissingManagedAppEnvMessage, resolveManagedAppRuntime } from '../../lib/app-runtime.js';
 import { renderTable } from '../../lib/ui.js';
 import { appRootPath, dbStatus, runtimeStatus, storagePath } from './shared.js';
@@ -42,14 +42,21 @@ function createGroupTable(title, values) {
 function serializeGroup(values) {
     return Object.fromEntries(Object.entries(values).map(([field, value]) => [field, normalizeJsonValue(value)]));
 }
-export default class AppInfo extends Command {
+export default class EnvInfo extends Command {
     static hidden = false;
-    static description = 'Show grouped details for the selected NocoBase app env, including app, database, API, and auth settings.';
+    static description = 'Show grouped details for the selected NocoBase env, including app, database, API, and auth settings.';
     static examples = [
+        '<%= config.bin %> <%= command.id %> app1',
+        '<%= config.bin %> <%= command.id %> app1 --json',
+        '<%= config.bin %> <%= command.id %> app1 --show-secrets',
         '<%= config.bin %> <%= command.id %> --env app1',
-        '<%= config.bin %> <%= command.id %> --env app1 --json',
-        '<%= config.bin %> <%= command.id %> --env app1 --show-secrets',
     ];
+    static args = {
+        name: Args.string({
+            description: 'CLI env name to inspect. Defaults to the current env when omitted',
+            required: false,
+        }),
+    };
     static flags = {
         env: Flags.string({
             char: 'e',
@@ -65,8 +72,13 @@ export default class AppInfo extends Command {
         }),
     };
     async run() {
-        const { flags } = await this.parse(AppInfo);
-        const requestedEnv = flags.env?.trim() || undefined;
+        const { args, flags } = await this.parse(EnvInfo);
+        const envNameArg = args.name?.trim() || undefined;
+        const envNameFlag = flags.env?.trim() || undefined;
+        if (envNameArg && envNameFlag && envNameArg !== envNameFlag) {
+            this.error(`Environment name was provided both as the argument ("${envNameArg}") and as --env ("${envNameFlag}"). Please use only one.`);
+        }
+        const requestedEnv = envNameArg || envNameFlag;
         const showSecrets = flags['show-secrets'];
         const runtime = await resolveManagedAppRuntime(requestedEnv);
         if (!runtime) {

package/dist/commands/env/list.js

@@ -7,30 +7,44 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 import { Command } from '@oclif/core';
+import { resolveManagedAppRuntime } from '../../lib/app-runtime.js';
 import { listEnvs } from '../../lib/auth-store.js';
 import { resolveDefaultConfigScope } from '../../lib/cli-home.js';
 import { renderTable } from '../../lib/ui.js';
-function resolveApiBaseUrl(config) {
-    return String(config.apiBaseUrl ?? config.baseUrl ?? config.apibaseUrl ?? '').trim();
-}
+import { apiStatus, appUrl, resolveApiBaseUrl } from './shared.js';
 export default class EnvList extends Command {
-    static summary = 'List configured environments';
+    static summary = 'List configured environments and API auth status';
     static examples = [
         '<%= config.bin %> <%= command.id %>',
     ];
     async run() {
         await this.parse(EnvList);
-        const { currentEnv, envs } = await listEnvs({ scope: resolveDefaultConfigScope() });
+        const scope = resolveDefaultConfigScope();
+        const { currentEnv, envs } = await listEnvs({ scope });
         const names = Object.keys(envs).sort();
         if (!names.length) {
             this.log('No envs configured.');
             this.log('Run `nb env add <name> --api-base-url <url>` to add one.');
             return;
         }
-        const rows = names.map((name) => {
+        const rows = [];
+        for (const name of names) {
             const env = envs[name];
-            return [name === currentEnv ? '*' : '', name, resolveApiBaseUrl(env), env.auth?.type ?? '', env.runtime?.version ?? ''];
-        });
-        this.log(renderTable(['Current', 'Name', 'Base URL', 'Auth', 'Runtime'], rows));
+            const runtime = await resolveManagedAppRuntime(name);
+            const statusConfig = {
+                ...env,
+                ...(runtime?.env.config ?? {}),
+            };
+            rows.push([
+                name === currentEnv ? '*' : '',
+                name,
+                runtime?.kind ?? env.kind ?? '-',
+                await apiStatus(name, statusConfig, { scope }),
+                runtime ? appUrl(runtime) : resolveApiBaseUrl(env),
+                env.auth?.type ?? '',
+                env.runtime?.version ?? '',
+            ]);
+        }
+        this.log(renderTable(['Current', 'Name', 'Kind', 'App Status', 'URL', 'Auth', 'Runtime'], rows));
     }
 }

package/dist/commands/{app → env}/shared.js

@@ -6,7 +6,8 @@
  * 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 { buildDockerDbContainerName, dockerContainerExists, dockerContainerIsRunning, defaultWorkspaceName, } from '../../lib/app-runtime.js';
+import { buildDockerDbContainerName, dockerContainerExists, dockerContainerIsRunning, } from '../../lib/app-runtime.js';
+import { executeRawApiRequest } from '../../lib/api-client.js';
 export function resolveApiBaseUrl(config) {
     return String(config.apiBaseUrl ?? config.baseUrl ?? config.apibaseUrl ?? '').trim();
 }
@@ -18,12 +19,6 @@ export function appUrl(runtime) {
     const baseUrl = resolveApiBaseUrl(runtime.env.config);
     return baseUrl.replace(/\/api\/?$/, '');
 }
-export function appNetwork(runtime) {
-    if (runtime.kind === 'docker') {
-        return runtime.workspaceName?.trim() || defaultWorkspaceName();
-    }
-    return '-';
-}
 export function appRootPath(runtime) {
     if (runtime.kind === 'http' || runtime.kind === 'docker') {
         return '-';
@@ -40,6 +35,74 @@ export function storagePath(runtime) {
     const value = String(runtime.env.storagePath ?? runtime.env.config.storagePath ?? '').trim();
     return value || '-';
 }
+function collectErrorCodes(value) {
+    if (!value || typeof value !== 'object') {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        return value.flatMap((item) => collectErrorCodes(item));
+    }
+    const out = [];
+    const record = value;
+    if (typeof record.code === 'string') {
+        out.push(record.code);
+    }
+    for (const key of ['data', 'error', 'errors']) {
+        out.push(...collectErrorCodes(record[key]));
+    }
+    return out;
+}
+function isAuthFailureData(value) {
+    const codes = collectErrorCodes(value);
+    return codes.some((code) => ['EMPTY_TOKEN', 'INVALID_TOKEN', 'EXPIRED_TOKEN', 'BLOCKED_TOKEN', 'EXPIRED_SESSION', 'NOT_EXIST_USER'].includes(code));
+}
+function isNetworkFailure(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return (error.name === 'AbortError'
+        || /fetch failed|network|timeout|timed out|abort|ECONNREFUSED|ECONNRESET|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|ENETUNREACH/i.test(error.message));
+}
+function isUnconfiguredFailure(error) {
+    return error instanceof Error && /missing (a )?base url|missing base URL/i.test(error.message);
+}
+function isAuthFailure(error) {
+    return (error instanceof Error
+        && /EMPTY_TOKEN|INVALID_TOKEN|EXPIRED_TOKEN|BLOCKED_TOKEN|EXPIRED_SESSION|NOT_EXIST_USER|invalid_grant|sign in|signin|authentication failed/i.test(error.message));
+}
+export async function apiStatus(envName, config, options = {}) {
+    if (!resolveApiBaseUrl(config)) {
+        return 'unconfigured';
+    }
+    try {
+        const response = await executeRawApiRequest({
+            envName,
+            scope: options.scope,
+            method: 'GET',
+            path: '/auth:check',
+            timeoutMs: options.timeoutMs ?? 2000,
+        });
+        if (response.ok) {
+            return 'ok';
+        }
+        if (response.status === 401 || response.status === 403 || isAuthFailureData(response.data)) {
+            return 'auth failed';
+        }
+        return 'error';
+    }
+    catch (error) {
+        if (isUnconfiguredFailure(error)) {
+            return 'unconfigured';
+        }
+        if (isAuthFailure(error)) {
+            return 'auth failed';
+        }
+        if (isNetworkFailure(error)) {
+            return 'unreachable';
+        }
+        return 'error';
+    }
+}
 async function isLocalAppHealthy(runtime) {
     const port = String(runtime.env.config.appPort ?? '').trim();
     if (!port) {

package/dist/commands/init.js

@@ -139,6 +139,12 @@ function logInitUiReady(command, url) {
 function logInitUiBrowserOpenFallback() {
     p.log.warn(translateCli('commands.init.messages.uiOpenBrowserFallback'));
 }
+function formatBrowserOpenError(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
 export default class Init extends Command {
     static summary = 'Set up NocoBase so coding agents can connect and work with it';
     static description = `Set up NocoBase for coding agents in the current workspace.
@@ -297,7 +303,6 @@ Prompt modes:
         }),
         'skip-skills': Flags.boolean({
             description: 'Skip installing or updating NocoBase AI coding skills during init',
-            hidden: true,
             default: false,
         }),
         'ui-host': Flags.string({
@@ -405,8 +410,9 @@ Prompt modes:
                 onServerStart: ({ url }) => {
                     logInitUiReady(this, url);
                 },
-                onOpenBrowserError: (_url, _err) => {
+                onOpenBrowserError: (_url, err) => {
                     logInitUiBrowserOpenFallback();
+                    p.log.info(`Browser open error: ${formatBrowserOpenError(err)}`);
                 },
             });
         }

package/dist/commands/install.js

@@ -18,6 +18,7 @@ import { runPromptCatalog, } from "../lib/prompt-catalog.js";
 import { applyCliLocale, localeText, resolveCliLocale, translateCli, } from "../lib/cli-locale.js";
 import { resolveConfiguredEnvPath, resolveDefaultConfigScope, resolveEnvRoot, resolveEnvRelativePath, } from '../lib/cli-home.js';
 import { findAvailableTcpPort, validateAvailableTcpPort, validateTcpPort, validateEnvKey, } from "../lib/prompt-validators.js";
+import { validateExternalDbConfig } from "../lib/db-connection-check.js";
 import { formatMissingManagedAppEnvMessage } from '../lib/app-runtime.js';
 import { run, runNocoBaseCommand } from '../lib/run-npm.js';
 import { startTask, stopTask, updateTask } from '../lib/ui.js';
@@ -180,6 +181,16 @@ function validateBuiltinDbEnabled(value, values) {
     }
     return translateCli('commands.install.validation.builtinDbUnsupported', { dialect });
 }
+async function validateExternalDbPromptField(value, values) {
+    const builtinDb = values.builtinDb === undefined ? true : Boolean(values.builtinDb);
+    if (builtinDb) {
+        return undefined;
+    }
+    if (typeof value === 'string' && value.trim() === '') {
+        return undefined;
+    }
+    return await validateExternalDbConfig(values);
+}
 function defaultInstallAppRootPath(envName) {
     const name = String(envName ?? DEFAULT_INSTALL_ENV_NAME).trim() || DEFAULT_INSTALL_ENV_NAME;
     return `./${name}/source/`;
@@ -447,6 +458,7 @@ export default class Install extends Command {
             initialValue: (values) => defaultDbHostForBuiltinDb(values),
             yesInitialValue: DEFAULT_INSTALL_BUILTIN_DB_HOST,
             required: true,
+            validate: validateExternalDbPromptField,
             hidden: (values) => Boolean(values.builtinDb),
         },
         dbPort: {
@@ -464,6 +476,7 @@ export default class Install extends Command {
             message: installText('prompts.dbDatabase.message'),
             initialValue: (values) => defaultDbDatabaseForDialect(values.dbDialect),
             required: true,
+            validate: validateExternalDbPromptField,
         },
         dbUser: {
             type: 'text',
@@ -471,6 +484,7 @@ export default class Install extends Command {
             initialValue: DEFAULT_INSTALL_DB_USER,
             yesInitialValue: DEFAULT_INSTALL_DB_USER,
             required: true,
+            validate: validateExternalDbPromptField,
         },
         dbPassword: {
             type: 'password',
@@ -478,6 +492,7 @@ export default class Install extends Command {
             initialValue: DEFAULT_INSTALL_DB_PASSWORD,
             yesInitialValue: DEFAULT_INSTALL_DB_PASSWORD,
             required: true,
+            validate: validateExternalDbPromptField,
         },
     };
     static rootUserPrompts = {
@@ -741,6 +756,9 @@ export default class Install extends Command {
         const builtinDb = values.builtinDb === undefined ? true : Boolean(values.builtinDb);
         const source = String(values.source ?? '').trim();
         if (!builtinDb || source === 'docker') {
+            if (!builtinDb) {
+                return await validateExternalDbConfig({ ...values, dbPort: value });
+            }
             return undefined;
         }
         return await Install.validateResumeAwareTcpPort(value, values, 'db');
@@ -765,6 +783,23 @@ export default class Install extends Command {
         });
         return reusesManagedPort ? undefined : portError;
     }
+    static async ensureExternalDbReadyForInstall(dbResults) {
+        const builtinDb = dbResults.builtinDb === undefined ? true : Boolean(dbResults.builtinDb);
+        if (builtinDb) {
+            return;
+        }
+        const dialect = String(dbResults.dbDialect ?? 'postgres').trim() || 'postgres';
+        const host = String(dbResults.dbHost ?? '').trim();
+        const port = String(dbResults.dbPort ?? '').trim();
+        const database = String(dbResults.dbDatabase ?? '').trim();
+        const address = host && port ? `${host}:${port}` : host || port || '(unknown address)';
+        const target = database ? `${address}/${database}` : address;
+        p.log.step(`Checking external ${dialect} database: ${target}`);
+        const validationError = await validateExternalDbConfig(dbResults);
+        if (validationError) {
+            throw new Error(validationError);
+        }
+    }
     static async readResumePortValidationContext(values) {
         if (!Boolean(values.resume)) {
             return undefined;
@@ -2044,6 +2079,7 @@ export default class Install extends Command {
         const workspaceName = usesDockerResources
             ? await Install.ensureWorkspaceName()
             : undefined;
+        await Install.ensureExternalDbReadyForInstall(dbResults);
         if (!parsed.resume) {
             await this.saveInstalledEnv({
                 envName,
@@ -2053,6 +2089,7 @@ export default class Install extends Command {
                 rootResults,
                 envAddResults,
             });
+            p.log.info(`Saved install config for env "${envName}"`);
         }
         let builtinDbPlan;
         if (Boolean(dbResults.builtinDb)) {

package/dist/lib/api-client.js

@@ -235,10 +235,24 @@ export async function executeRawApiRequest(options) {
         }
         url.searchParams.set(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
     }
-    const response = await fetchWithPreservedAuthRedirect(url.toString(), {
-        method: options.method.toUpperCase(),
-        headers,
-        body: options.body === undefined ? undefined : JSON.stringify(options.body),
-    });
-    return parseResponse(response);
+    const controller = options.timeoutMs && options.timeoutMs > 0 ? new AbortController() : undefined;
+    const timeout = controller
+        ? setTimeout(() => {
+            controller.abort();
+        }, options.timeoutMs)
+        : undefined;
+    try {
+        const response = await fetchWithPreservedAuthRedirect(url.toString(), {
+            method: options.method.toUpperCase(),
+            headers,
+            body: options.body === undefined ? undefined : JSON.stringify(options.body),
+            signal: controller?.signal,
+        });
+        return parseResponse(response);
+    }
+    finally {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+    }
 }

package/dist/lib/db-connection-check.js

@@ -0,0 +1,178 @@
+/**
+ * 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 { translateCli } from "./cli-locale.js";
+import { validateTcpPort } from "./prompt-validators.js";
+const DB_CONNECTION_TIMEOUT_MS = 5_000;
+const externalDbValidationCache = new Map();
+function trimPromptValue(value) {
+    return String(value ?? '').trim();
+}
+export function readExternalDbConnectionConfig(values) {
+    const builtinDb = values.builtinDb === undefined ? true : Boolean(values.builtinDb);
+    if (builtinDb) {
+        return undefined;
+    }
+    const dialect = trimPromptValue(values.dbDialect || 'postgres');
+    if (dialect !== 'postgres' && dialect !== 'kingbase' && dialect !== 'mysql' && dialect !== 'mariadb') {
+        return undefined;
+    }
+    const host = trimPromptValue(values.dbHost);
+    const portText = trimPromptValue(values.dbPort);
+    const database = trimPromptValue(values.dbDatabase);
+    const user = trimPromptValue(values.dbUser);
+    const password = String(values.dbPassword ?? '');
+    if (!host || !portText || !database || !user || !password) {
+        return undefined;
+    }
+    if (validateTcpPort(portText)) {
+        return undefined;
+    }
+    return {
+        dialect,
+        host,
+        port: Number.parseInt(portText, 10),
+        database,
+        user,
+        password,
+    };
+}
+export function formatDbCheckAddress(config) {
+    return `${config.host}:${config.port}/${config.database}`;
+}
+function buildValidationCacheKey(config) {
+    return JSON.stringify(config);
+}
+function formatDbConnectionError(config, error) {
+    const maybeError = error;
+    const code = String(maybeError?.code ?? '').trim().toUpperCase();
+    const errno = typeof maybeError?.errno === 'number' ? maybeError.errno : undefined;
+    const rawMessage = String(maybeError?.message || maybeError?.sqlMessage || error || '').trim();
+    if (code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'EHOSTUNREACH' || code === 'ECONNRESET') {
+        return translateCli('validators.dbConnection.unreachable', {
+            host: config.host,
+            port: config.port,
+            details: rawMessage,
+        });
+    }
+    if (code === 'ETIMEDOUT') {
+        return translateCli('validators.dbConnection.timeout', {
+            host: config.host,
+            port: config.port,
+            seconds: Math.ceil(DB_CONNECTION_TIMEOUT_MS / 1000),
+        });
+    }
+    if (code === '28P01' || code === '28000' || code === 'ER_ACCESS_DENIED_ERROR' || errno === 1045) {
+        return translateCli('validators.dbConnection.authenticationFailed', {
+            user: config.user,
+            database: config.database,
+        });
+    }
+    if (code === '3D000' || code === 'ER_BAD_DB_ERROR' || errno === 1049) {
+        return translateCli('validators.dbConnection.databaseNotFound', {
+            database: config.database,
+        });
+    }
+    return translateCli('validators.dbConnection.connectionFailed', {
+        details: rawMessage || code || String(error),
+    });
+}
+async function checkPostgresFamilyConnection(config) {
+    const { default: pg } = await import('pg');
+    const client = new pg.Client({
+        host: config.host,
+        port: config.port,
+        user: config.user,
+        password: config.password,
+        database: config.database,
+        connectionTimeoutMillis: DB_CONNECTION_TIMEOUT_MS,
+    });
+    try {
+        await client.connect();
+        await client.query('SELECT 1');
+    }
+    finally {
+        await Promise.resolve(client.end()).catch(() => undefined);
+    }
+}
+async function checkMysqlConnection(config) {
+    const { default: mysql } = await import('mysql2/promise');
+    const connection = await mysql.createConnection({
+        host: config.host,
+        port: config.port,
+        user: config.user,
+        password: config.password,
+        database: config.database,
+        connectTimeout: DB_CONNECTION_TIMEOUT_MS,
+    });
+    try {
+        await connection.query('SELECT 1');
+    }
+    finally {
+        await Promise.resolve(connection.end()).catch(() => undefined);
+    }
+}
+async function checkMariaDbConnection(config) {
+    const { default: mariadb } = await import('mariadb');
+    const connection = await mariadb.createConnection({
+        host: config.host,
+        port: config.port,
+        user: config.user,
+        password: config.password,
+        database: config.database,
+        connectTimeout: DB_CONNECTION_TIMEOUT_MS,
+    });
+    try {
+        await connection.query('SELECT 1');
+    }
+    finally {
+        await Promise.resolve(connection.end()).catch(() => undefined);
+    }
+}
+async function performExternalDbConnectionCheck(config) {
+    try {
+        switch (config.dialect) {
+            case 'postgres':
+            case 'kingbase': {
+                await checkPostgresFamilyConnection(config);
+                return undefined;
+            }
+            case 'mysql': {
+                await checkMysqlConnection(config);
+                return undefined;
+            }
+            case 'mariadb': {
+                await checkMariaDbConnection(config);
+                return undefined;
+            }
+        }
+    }
+    catch (error) {
+        return formatDbConnectionError(config, error);
+    }
+}
+export async function checkExternalDbConnection(config) {
+    const cacheKey = buildValidationCacheKey(config);
+    const cached = externalDbValidationCache.get(cacheKey);
+    if (cached) {
+        return await cached;
+    }
+    const pending = performExternalDbConnectionCheck(config);
+    externalDbValidationCache.set(cacheKey, pending);
+    return await pending;
+}
+export async function validateExternalDbConfig(values) {
+    const config = readExternalDbConnectionConfig(values);
+    if (!config) {
+        return undefined;
+    }
+    return await checkExternalDbConnection(config);
+}
+export function clearExternalDbValidationCache() {
+    externalDbValidationCache.clear();
+}

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

@@ -559,17 +559,23 @@ function readFormFromClientStrippingPwcMeta(o) {
     const { [PWC_FORM_META_STEP]: _meta, ...rest } = o;
     return rest;
 }
-function openUrlInDefaultBrowser(url) {
+function openUrlInDefaultBrowser(url, onError) {
+    const reportError = (error) => {
+        onError?.(url, error);
+    };
     const platform = process.platform;
+    let child;
     if (platform === 'darwin') {
-        spawn('open', [url], { stdio: 'ignore', detached: true }).unref();
+        child = spawn('open', [url], { stdio: 'ignore', detached: true });
     }
     else if (platform === 'win32') {
-        spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true, windowsHide: true }).unref();
+        child = spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true, windowsHide: true });
     }
     else {
-        spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).unref();
+        child = spawn('xdg-open', [url], { stdio: 'ignore', detached: true });
     }
+    child.once('error', reportError);
+    child.unref();
 }
 function closePromptWebUiServer(server, done) {
     server.close(done);
@@ -2084,11 +2090,12 @@ function runPromptCatalogWebUIImpl(options) {
             const port = addr.port;
             const startUrl = `http://${host}:${port}/`;
             options.onServerStart?.({ host, port, url: startUrl });
+            const onOpenBrowserError = options.onOpenBrowserError ?? ((u, err) => console.warn(String(err), u));
             try {
-                openUrlInDefaultBrowser(startUrl);
+                openUrlInDefaultBrowser(startUrl, onOpenBrowserError);
             }
             catch (e) {
-                (options.onOpenBrowserError ?? ((u, err) => console.warn(String(err), u)))(startUrl, e);
+                onOpenBrowserError(startUrl, e);
             }
             timeoutId = setTimeout(() => rejectAndClose(new Error('Local UI timeout — close the tab and try again, or resubmit within the time limit.')), timeoutMs);
         });

package/dist/lib/startup-update.js

@@ -20,7 +20,10 @@ function getStateFile() {
     return path.join(resolveCliHomeDir('global'), STARTUP_UPDATE_STATE_FILE);
 }
 function todayStamp(now = new Date()) {
-    return now.toISOString().slice(0, 10);
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const day = String(now.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
 }
 function shouldSkipByArgv(argv) {
     const tokens = argv.filter((token) => token && !token.startsWith('-'));

package/dist/locale/en-US.json

@@ -62,6 +62,13 @@
       "allocateNotDockerPublished": "Failed to allocate an available TCP port that is not already published by Docker.",
       "alreadyInUse": "Port {{port}} is already in use. Choose another port.",
       "alreadyInUseByDocker": "Port {{port}} is already in use by a Docker container. Choose another port."
+    },
+    "dbConnection": {
+      "unreachable": "Can't reach the database at {{host}}:{{port}}. Check the host, port, and network connectivity. Details: {{details}}",
+      "timeout": "Timed out connecting to the database at {{host}}:{{port}} after about {{seconds}} seconds.",
+      "authenticationFailed": "Failed to sign in to database \"{{database}}\" with user \"{{user}}\". Check the username and password.",
+      "databaseNotFound": "Database \"{{database}}\" does not exist or is not accessible with the current connection settings.",
+      "connectionFailed": "Database connection check failed. Details: {{details}}"
     }
   },
   "commands": {
@@ -273,7 +280,7 @@
         "envExists": "Env \"{{envName}}\" already exists. Choose another env name."
       },
       "messages": {
-        "title": "Set Up Your NocoBase AI Workspace",
+        "title": "Set Up NocoBase for Coding Agents",
         "appNameRequiredWhenSkipped": "Env name is required when prompts are skipped.",
         "appNameEnvHelp": "Use `nb init --yes --env <envName>` to continue.",
         "resumeEnvRequired": "Env name is required when resuming setup.",
@@ -303,24 +310,24 @@
         }
       },
       "webUi": {
-        "pageTitle": "Set Up Your NocoBase AI Workspace",
-        "documentHeading": "Set Up Your NocoBase AI Workspace",
-        "documentHint": "Connect an existing NocoBase app, or install a new one and connect it, so coding agents can work with NocoBase in this workspace.",
+        "pageTitle": "Set Up NocoBase for Coding Agents",
+        "documentHeading": "Set Up NocoBase for Coding Agents",
+        "documentHint": "Connect an existing NocoBase app, or install a new one, so coding agents can access and work with NocoBase.",
         "gettingStarted": {
           "title": "Getting started",
-          "description": "Pick your setup path."
+          "description": "Choose whether to connect an existing app or install a new one."
         },
         "connectExistingApp": {
           "title": "Connect an existing app",
-          "description": "Add your app connection."
+          "description": "Save your app connection."
         },
         "createNewApp": {
-          "title": "Create a new app",
-          "description": "Set project basics."
+          "title": "Install a new app",
+          "description": "Set app basics and install options."
         },
         "downloadAppFiles": {
           "title": "Download app files",
-          "description": "Choose source and options."
+          "description": "Choose how to get the app files."
         },
         "configureDatabase": {
           "title": "Configure the database",

package/dist/locale/zh-CN.json

@@ -62,6 +62,13 @@
       "allocateNotDockerPublished": "分配未被 Docker 占用的可用 TCP 端口失败。",
       "alreadyInUse": "端口 {{port}} 已被占用，请更换其他端口。",
       "alreadyInUseByDocker": "端口 {{port}} 已被 Docker 容器占用，请更换其他端口。"
+    },
+    "dbConnection": {
+      "unreachable": "无法连接到数据库 {{host}}:{{port}}。请检查主机、端口和网络连通性。详情：{{details}}",
+      "timeout": "连接数据库 {{host}}:{{port}} 超时，约 {{seconds}} 秒内未成功建立连接。",
+      "authenticationFailed": "无法使用用户 \"{{user}}\" 登录数据库 \"{{database}}\"。请检查用户名和密码。",
+      "databaseNotFound": "数据库 \"{{database}}\" 不存在，或当前连接配置无权访问该数据库。",
+      "connectionFailed": "数据库连接检查失败。详情：{{details}}"
     }
   },
   "commands": {
@@ -273,7 +280,7 @@
         "envExists": "Env \"{{envName}}\" 已存在，请换一个 env name。"
       },
       "messages": {
-        "title": "初始化你的 NocoBase AI 工作区",
+        "title": "配置供 Coding Agents 使用的 NocoBase",
         "appNameRequiredWhenSkipped": "跳过 prompts 时必须提供 Env name。",
         "appNameEnvHelp": "请使用 `nb init --yes --env <envName>` 继续。",
         "resumeEnvRequired": "恢复安装时必须提供 Env name。",
@@ -303,24 +310,24 @@
         }
       },
       "webUi": {
-        "pageTitle": "初始化你的 NocoBase AI 工作区",
-        "documentHeading": "初始化你的 NocoBase AI 工作区",
-        "documentHint": "连接已有的 NocoBase 应用，或安装一个新的应用后再完成连接，让 Coding Agents 可以在当前工作区中结合 NocoBase 协同工作。",
+        "pageTitle": "配置供 Coding Agents 使用的 NocoBase",
+        "documentHeading": "配置供 Coding Agents 使用的 NocoBase",
+        "documentHint": "连接已有的 NocoBase 应用，或安装一个新的应用，让 Coding Agents 可以在当前工作区中访问和操作 NocoBase。",
         "gettingStarted": {
           "title": "开始设置",
-          "description": "选择你的配置路径。"
+          "description": "选择连接已有应用，或安装一个新应用。"
         },
         "connectExistingApp": {
           "title": "连接已有应用",
-          "description": "添加现有应用连接。"
+          "description": "保存现有应用连接。"
         },
         "createNewApp": {
-          "title": "创建新应用",
-          "description": "设置项目基础信息。"
+          "title": "安装新应用",
+          "description": "设置应用基础信息和安装选项。"
         },
         "downloadAppFiles": {
           "title": "下载应用文件",
-          "description": "选择来源和下载选项。"
+          "description": "选择获取应用文件的方式。"
         },
         "configureDatabase": {
           "title": "配置数据库",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/cli",
-  "version": "2.1.0-beta.22",
+  "version": "2.1.0-beta.24",
   "description": "NocoBase Command Line Tool",
   "type": "module",
   "main": "dist/generated/command-registry.js",
@@ -37,7 +37,7 @@
     "topicSeparator": " ",
     "topics": {
       "app": {
-        "description": "Manage NocoBase app runtimes: start, stop, restart, logs, status, and upgrades."
+        "description": "Manage NocoBase app runtimes: start, stop, restart, logs, and upgrades."
       },
       "source": {
         "description": "Work with the local NocoBase source project: download, develop, build, and test."
@@ -56,7 +56,7 @@
         "description": "Manage the built-in database for the selected env."
       },
       "env": {
-        "description": "Manage NocoBase project environments and update command runtimes."
+        "description": "Manage NocoBase project environments, status, details, and command runtimes."
       },
       "self": {
         "description": "Inspect or update the NocoBase CLI itself."
@@ -78,8 +78,11 @@
     "@oclif/core": "^4.10.4",
     "cross-spawn": "^7.0.6",
     "lodash": "^4.17.21",
+    "mariadb": "^2.5.6",
+    "mysql2": "^3.14.0",
     "openapi-types": "^12.1.3",
     "ora": "^8.2.0",
+    "pg": "^8.14.1",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {
@@ -91,5 +94,5 @@
     "type": "git",
     "url": "git+https://github.com/nocobase/nocobase.git"
   },
-  "gitHead": "53ad02861ed8e813103f59659804417118c85b4c"
+  "gitHead": "f77b85530a2d127d9bfe4dca3a26fbb02c1139ba"
 }

package/dist/commands/app/ps.js

@@ -1,60 +0,0 @@
-/**
- * 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 { listEnvs } from '../../lib/auth-store.js';
-import { renderTable } from '../../lib/ui.js';
-import { appNetwork, appRootPath, appUrl, dbStatus, runtimeStatus, storagePath } from './shared.js';
-export default class AppPs extends Command {
-    static hidden = false;
-    static description = 'Show NocoBase runtime status for configured envs without starting or stopping anything.';
-    static examples = [
-        '<%= config.bin %> <%= command.id %>',
-        '<%= config.bin %> <%= command.id %> --env app1',
-    ];
-    static flags = {
-        env: Flags.string({
-            char: 'e',
-            description: 'CLI env name to inspect. Omit to show all configured envs',
-        }),
-    };
-    async run() {
-        const { flags } = await this.parse(AppPs);
-        const requestedEnv = flags.env?.trim() || undefined;
-        const envNames = requestedEnv
-            ? [requestedEnv]
-            : Object.keys((await listEnvs()).envs).sort();
-        if (!envNames.length) {
-            this.log('No NocoBase env is configured yet. Run `nb init` to create one first.');
-            return;
-        }
-        const rows = [];
-        for (const envName of envNames) {
-            const runtime = await resolveManagedAppRuntime(envName);
-            if (!runtime) {
-                if (requestedEnv) {
-                    this.error(formatMissingManagedAppEnvMessage(envName));
-                }
-                rows.push([envName, '-', 'missing', '-', '-', '-', '-', '']);
-                continue;
-            }
-            rows.push([
-                runtime.envName,
-                runtime.kind,
-                await runtimeStatus(runtime),
-                await dbStatus(runtime),
-                appNetwork(runtime),
-                appRootPath(runtime),
-                storagePath(runtime),
-                appUrl(runtime),
-            ]);
-        }
-        this.log(renderTable(['Env', 'Kind', 'App Status', 'Database Status', 'Network', 'App Root', 'Storage', 'URL'], rows));
-    }
-}

package/dist/commands/ps.js

@@ -1,12 +0,0 @@
-/**
- * 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 AppPs from './app/ps.js';
-export default class Ps extends AppPs {
-    static hidden = true;
-}