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

package/README.zh-CN.md

@@ -0,0 +1,332 @@
+# NocoBase CLI
+
+NocoBase CLI (`nb`) 是用于在本地工作区初始化、连接和管理 NocoBase 应用的命令行工具。它可以帮助你准备 NocoBase 应用、保存 CLI env 配置，并提供启动、停止、查看日志、升级和清理等日常管理命令，让 coding agent 可以连接并使用 NocoBase。
+
+CLI 支持两种常见的初始化方式：
+
+- 连接已有的 NocoBase 应用，让 coding agent 直接使用。
+- 通过 Docker、npm 或 Git 安装一个新的 NocoBase 应用，并保存为 CLI env。
+
+## 前提条件
+
+- Node.js v20+
+- Yarn 1.x
+- Git：选择 Git 源码安装时需要
+- Docker：使用 Docker 方式安装，或使用内置数据库时需要
+
+## 安装
+
+全局安装 CLI：
+
+```bash
+npm install -g @nocobase/cli@alpha
+```
+
+查看可用命令：
+
+```bash
+nb --help
+nb init --help
+```
+
+## 核心概念
+
+- **Workspace**：当前项目目录，CLI 会在这里保存 `.nocobase` 配置。
+- **Env**：CLI 保存的一个 NocoBase 连接配置。在 `nb init` 中，app name 也就是 env name。
+- **Source**：本地应用的来源，支持 `docker`、`npm` 和 `git`。
+- **Remote env**：只保存已有 NocoBase 应用 API 连接的 env。
+- **Runtime resources**：由 CLI 管理的本地运行资源，包括应用进程、Docker 应用容器、内置数据库容器、源码目录和存储目录。
+
+## 快速开始
+
+### 交互式初始化
+
+在终端中启动引导式初始化：
+
+```bash
+nb init
+```
+
+使用浏览器表单完成初始化：
+
+```bash
+nb init --ui
+```
+
+`nb init` 可以连接已有的 NocoBase 应用，也可以安装一个新的 NocoBase 应用。创建新应用时，还可以为当前工作区安装 NocoBase AI coding skills (`nocobase/skills`)。
+
+### 非交互式初始化
+
+跳过交互提示时，必须提供 app/env name：
+
+```bash
+nb init --env app1 --yes
+```
+
+使用 Docker 安装：
+
+```bash
+nb init --env app1 --yes --source docker --version alpha
+```
+
+使用 npm 安装：
+
+```bash
+nb init --env app1 --yes --source npm --version alpha --app-port 13080
+```
+
+使用 Git 源码安装：
+
+```bash
+nb init --env app1 --yes --source git --version alpha
+```
+
+对于 Git 源码安装，`--version alpha` 实际会解析为 `develop` 分支。
+
+使用 Git 分支安装：
+
+```bash
+nb init --env app1 --yes --source git --version fix/cli-v2
+```
+
+`--version` 是三种 source 共用的版本参数：
+
+- npm：包版本号
+- Docker：镜像 tag
+- Git：git ref，例如 branch 或 tag
+
+默认情况下，新建本地应用会使用以下目录：
+
+- 源码目录：`./<envName>/source/`
+- 存储目录：`./<envName>/storage/`
+
+### 恢复中断的初始化
+
+如果 `nb init` 在 env 配置已经保存之后中断了，可以继续上一次初始化流程：
+
+```bash
+nb init --env app1 --resume
+```
+
+对应的底层高级命令是：
+
+```bash
+nb install --env app1 --resume
+```
+
+`--resume` 会复用工作区里已保存的 env config，包括应用、source、数据库和 env 连接相关配置。在交互模式下，只会继续补齐缺失的初始化参数。
+
+在非交互模式下，需要重新传这些只用于初始化、不会保存到 env config 的参数：
+
+- `--lang`
+- `--root-username`
+- `--root-email`
+- `--root-password`
+- `--root-nickname`
+
+## 常用命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `nb init` | 初始化 NocoBase，并连接为 coding agent 可使用的 CLI env。 |
+| `nb install` | `nb init` 内部会使用的高级命令，用于安装本地 NocoBase 应用并保存 env 配置。通常建议直接使用 `nb init`。 |
+| `nb download` | `nb init` 或 `nb upgrade` 会使用的高级命令，用于从 Docker、npm 或 Git 获取 NocoBase。通常很少直接使用。 |
+| `nb start` | 启动选中的本地应用或 Docker 容器。 |
+| `nb stop` | 停止选中的本地应用或 Docker 容器。 |
+| `nb dev` | 为 npm/Git 源码 env 启动开发模式。 |
+| `nb logs` | 查看 npm/Git 或 Docker env 的应用日志。 |
+| `nb ps` | 查看已配置 env 的运行状态。 |
+| `nb db` | 查看或管理本地 env 的内置数据库运行状态。 |
+| `nb upgrade` | 更新源码/镜像并重启选中的应用。 |
+| `nb down` | 停止并移除某个 env 的本地运行容器。 |
+| `nb env` | 管理已保存的 CLI env 连接。 |
+| `nb api` | 通过 CLI 调用 NocoBase API 资源。 |
+| `nb pm` | 管理选中 NocoBase env 的插件。 |
+
+推荐在应用和运行时相关命令里显式使用 `--env`；`-e` 是它的简写：
+
+```bash
+nb start --env app1
+nb logs --env app1
+nb ps --env app1
+nb db ps --env app1
+```
+
+等价的简写示例：
+
+```bash
+nb start -e app1
+nb logs -e app1
+nb upgrade -e app1
+nb db start -e app1
+```
+
+## 运行方式
+
+### Docker
+
+Docker env 会通过已保存的 Docker 容器和镜像进行管理：
+
+```bash
+nb init --env app1 --yes --source docker --version alpha
+nb start --env app1
+nb logs --env app1
+nb stop --env app1
+```
+
+Docker 下载支持指定平台：
+
+```bash
+nb download --source docker --version alpha --docker-platform auto
+nb download --source docker --version alpha --docker-platform linux/amd64
+nb download --source docker --version alpha --docker-platform linux/arm64
+```
+
+### npm 和 Git
+
+npm 和 Git env 会使用本地源码目录，并支持开发模式：
+
+```bash
+nb init --env app1 --yes --source git --version alpha
+nb dev --env app1
+```
+
+`nb dev` 只支持 npm/Git 源码 env。Docker env 可以通过 `nb logs` 查看日志，remote env 只支持 API 和 env 相关操作。
+
+### 已有 NocoBase 应用
+
+如果要连接已有应用，可以运行 `nb init` 并选择已有应用流程，也可以直接添加 env：
+
+```bash
+nb env add app1 --base-url http://localhost:13000/api
+```
+
+`nb env add` 会在需要时自动进入认证流程。
+
+## 升级
+
+升级会更新已保存的源码或镜像，然后重启应用：
+
+```bash
+nb upgrade --env app1
+```
+
+如果只想使用当前已保存的本地源码或 Docker 镜像重启应用，可以使用 `--skip-code-update` 或 `-s`：
+
+```bash
+nb upgrade --env app1 -s
+```
+
+## 数据库命令
+
+可以使用 `nb db` 查看或管理本地 env 的内置数据库运行状态：
+
+```bash
+nb db ps
+nb db ps --env app1
+nb db start --env app1
+nb db stop --env app1
+nb db logs --env app1
+```
+
+说明：
+
+- `nb db start` 和 `nb db stop` 只适用于启用了内置数据库的 env。
+- `nb db logs` 只适用于启用了内置数据库的 env。
+- 对于没有 CLI 托管数据库容器的 env，`nb db ps` 也会显示 `external` 或 `remote` 状态。
+
+## 清理
+
+关闭并清理某个本地 env：
+
+```bash
+nb down --env app1
+```
+
+默认情况下，`nb down` 会停止应用，并在存在时移除应用容器和数据库容器。它不会删除用户数据、源码文件和 CLI env 配置。
+
+如需执行破坏性清理，需要显式指定参数：
+
+```bash
+nb down --env app1 --remove-data
+nb down --env app1 --remove-source
+nb down --env app1 --remove-env
+```
+
+- `--remove-data`：删除 storage 和托管数据库数据。除非使用 `--yes`，否则需要二次确认。
+- `--remove-source`：删除 npm/Git 源码目录。
+- `--remove-env`：删除已保存的 CLI env 配置。
+
+## Env 管理
+
+查看当前 env：
+
+```bash
+nb env
+```
+
+查看已配置的 env：
+
+```bash
+nb env list
+```
+
+切换当前 env：
+
+```bash
+nb env use app1
+```
+
+当凭证需要刷新时，重新认证某个 env：
+
+```bash
+nb env auth app1
+```
+
+从选中的应用更新运行时命令元数据：
+
+```bash
+nb env update app1
+```
+
+## API 命令
+
+CLI 可以通过已配置的 env 调用 NocoBase 资源 API：
+
+```bash
+nb api resource list --resource users -e app1
+nb api resource get --resource users --filter-by-tk 1 -e app1
+nb api resource create --resource users --values '{"nickname":"Ada"}' -e app1
+```
+
+如果需要输出原始 JSON，可以使用 `-j, --json-output`：
+
+```bash
+nb api resource list --resource users -e app1 -j
+```
+
+可用的 API 命令分类：
+
+| 命令 | 说明 |
+| --- | --- |
+| `nb api acl` | 基于角色、资源和操作管理访问控制。 |
+| `nb api api-keys` | 管理用于 HTTP API 访问的 API keys。 |
+| `nb api app` | 管理应用相关资源。 |
+| `nb api authenticators` | 管理用户认证，包括密码认证、短信认证、SSO 协议和可扩展认证方式。 |
+| `nb api data-modeling` | 管理数据源、数据表和数据库建模资源。 |
+| `nb api file-manager` | 管理文件存储服务、文件集合和附件字段。 |
+| `nb api flow-surfaces` | 组合和更新页面、标签页、区块、字段和操作等界面结构。 |
+| `nb api pm` | 通过 API 命令管理插件。 |
+| `nb api resource` | 操作通用集合资源。 |
+| `nb api system-settings` | 调整系统标题、Logo、语言和其他全局设置。 |
+| `nb api theme-editor` | 自定义 UI 颜色和尺寸，保存并切换主题。 |
+| `nb api workflow` | 管理用于业务自动化的工作流资源。 |
+
+## 本地数据
+
+CLI 会在工作区的 `.nocobase` 中保存配置：
+
+- `config.json`：env 定义、当前 env 和工作区级配置。
+- `versions/<version>/commands.json`：从目标应用生成并缓存的运行时命令。
+
+源码文件、storage 文件、Docker 容器和数据库数据等运行时数据，会根据 env 的 source 和安装选项分别管理。

package/bin/run.js

@@ -2,10 +2,12 @@
 
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const requireFromCli = createRequire(import.meta.url);
 const root = path.resolve(__dirname, '..');
 const realRoot = fs.realpathSync(root);
 const isSourcePackage = realRoot.split(path.sep).join('/').endsWith('/packages/core/cli');
@@ -15,13 +17,30 @@ if (process.env.NB_CLI_USE_DIST === '1') {
 }
 
 /**
- * In the monorepo, plain `node` cannot load `.ts`. Re-exec once with `--import tsx`
+ * In the monorepo, plain `node` cannot load `.ts`. Re-exec once with `--import <tsx>`
  * (same effect as a dedicated dev entry with `#!/usr/bin/env -S node --import tsx`).
+ *
+ * Use the tsx package resolved from this CLI install (not CWD), so `nb` works when
+ * invoked from a project directory that does not depend on `tsx`.
  */
 function reexecWithTsx() {
+  let tsxEntry;
+  try {
+    tsxEntry = requireFromCli.resolve('tsx');
+  } catch {
+    console.error(
+      [
+        'Cannot load dev dependency `tsx` for the NocoBase CLI.',
+        'Install monorepo dependencies (e.g. `yarn install` at the repo root),',
+        'or set NB_CLI_USE_DIST=1 to run the compiled CLI without TypeScript sources.',
+      ].join(' '),
+    );
+    process.exit(1);
+  }
+
   const result = spawnSync(
     process.execPath,
-    ['--import', 'tsx', '--disable-warning=ExperimentalWarning', ...process.argv.slice(1)],
+    ['--import', pathToFileURL(tsxEntry).href, '--disable-warning=ExperimentalWarning', ...process.argv.slice(1)],
     {
       stdio: 'inherit',
       env: {

package/dist/commands/build.js

@@ -8,6 +8,7 @@
  */
 import { Args, Command, Flags } from '@oclif/core';
 import { runNocoBaseCommand } from "../lib/run-npm.js";
+import { setVerboseMode } from '../lib/ui.js';
 export default class Build extends Command {
     static args = {
         /** Matches `nb build @nocobase/acl @nocobase/actions` — zero or more package names. */
@@ -29,9 +30,11 @@ export default class Build extends Command {
         'cwd': Flags.string({ description: 'Current working directory', char: 'c', required: false }),
         'no-dts': Flags.boolean({ description: 'not generate dts' }),
         sourcemap: Flags.boolean({ description: 'generate sourcemap' }),
+        verbose: Flags.boolean({ description: 'Show detailed command output', default: false }),
     };
     async run() {
         const { args, flags } = await this.parse(Build);
+        setVerboseMode(flags.verbose);
         const packages = args.packages ?? [];
         const npmArgs = ['build', ...packages];
         if (flags['no-dts']) {
@@ -41,7 +44,10 @@ export default class Build extends Command {
             npmArgs.push('--sourcemap');
         }
         try {
-            await runNocoBaseCommand(npmArgs, { cwd: flags['cwd'] });
+            await runNocoBaseCommand(npmArgs, {
+                cwd: flags['cwd'],
+                stdio: flags.verbose ? 'inherit' : 'ignore',
+            });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);

package/dist/commands/db/logs.js

@@ -0,0 +1,85 @@
+/**
+ * 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 { run } from '../../lib/run-npm.js';
+import { printInfo } from '../../lib/ui.js';
+import { formatUnmanagedDbLogsMessage, resolveDbRuntime } from './shared.js';
+function formatDbLogsFailure(envName, message) {
+    if (/does not exist/i.test(message)) {
+        return [
+            `Can't show database logs for "${envName}" yet.`,
+            'The saved built-in database container for this env could not be found on this machine.',
+            'Try reinstalling the env, or check whether the container was removed outside the CLI.',
+            `Details: ${message}`,
+        ].join('\n');
+    }
+    return [
+        `Couldn't show database logs for "${envName}".`,
+        'Check that the built-in database runtime for this env is still available, then try again.',
+        `Details: ${message}`,
+    ].join('\n');
+}
+export default class DbLogs extends Command {
+    static description = 'Show logs for the built-in database container of the selected env.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> --env app1',
+        '<%= config.bin %> <%= command.id %> --env app1 --tail 200',
+        '<%= config.bin %> <%= command.id %> --env app1 --no-follow',
+    ];
+    static flags = {
+        env: Flags.string({
+            char: 'e',
+            description: 'CLI env name to inspect built-in database logs for. Defaults to the current env when omitted',
+        }),
+        tail: Flags.integer({
+            description: 'Number of recent log lines to show before following',
+            default: 100,
+            min: 0,
+        }),
+        follow: Flags.boolean({
+            char: 'f',
+            description: 'Keep streaming new log lines',
+            default: true,
+            allowNo: true,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(DbLogs);
+        const requestedEnv = flags.env?.trim() || undefined;
+        const runtime = await resolveDbRuntime(requestedEnv);
+        if (!runtime) {
+            this.error(formatMissingManagedAppEnvMessage(requestedEnv));
+        }
+        if (runtime.kind !== 'builtin') {
+            this.error(formatUnmanagedDbLogsMessage(runtime));
+        }
+        const tail = String(flags.tail ?? 100);
+        const follow = flags.follow !== false;
+        printInfo(follow
+            ? `Showing built-in database logs for "${runtime.envName}" (press Ctrl+C to stop).`
+            : `Showing recent built-in database logs for "${runtime.envName}".`);
+        const dockerArgs = ['logs', '--tail', tail];
+        if (follow) {
+            dockerArgs.push('--follow');
+        }
+        dockerArgs.push(runtime.containerName);
+        try {
+            await run('docker', dockerArgs, {
+                errorName: 'docker logs',
+                stdio: 'inherit',
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.error(formatDbLogsFailure(runtime.envName, message));
+        }
+    }
+}

package/dist/commands/db/ps.js

@@ -0,0 +1,60 @@
+/**
+ * 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 { listEnvs } from '../../lib/auth-store.js';
+import { renderTable } from '../../lib/ui.js';
+import { builtinDbStatus, resolveDbRuntime } from './shared.js';
+export default class DbPs extends Command {
+    static description = 'Show built-in database 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(DbPs);
+        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 resolveDbRuntime(envName);
+            if (!runtime) {
+                if (requestedEnv) {
+                    this.error(formatMissingManagedAppEnvMessage(envName));
+                }
+                rows.push([envName, '-', '-', 'missing', '']);
+                continue;
+            }
+            const type = runtime.kind === 'builtin' ? 'builtin' : runtime.status;
+            const status = runtime.kind === 'builtin'
+                ? await builtinDbStatus(runtime.containerName)
+                : runtime.status;
+            rows.push([
+                runtime.envName,
+                type,
+                runtime.dbDialect,
+                status,
+                runtime.address,
+            ]);
+        }
+        this.log(renderTable(['Env', 'Type', 'Dialect', 'Status', 'Address'], rows));
+    }
+}

package/dist/commands/db/shared.js

@@ -0,0 +1,81 @@
+/**
+ * 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 { buildDockerDbContainerName, dockerContainerExists, dockerContainerIsRunning, resolveManagedAppRuntime, } from '../../lib/app-runtime.js';
+function formatAddress(host, port, fallbackHost) {
+    const normalizedHost = String(host ?? '').trim() || String(fallbackHost ?? '').trim();
+    const normalizedPort = String(port ?? '').trim();
+    if (normalizedHost && normalizedPort) {
+        return `${normalizedHost}:${normalizedPort}`;
+    }
+    return normalizedHost || normalizedPort || '';
+}
+export async function resolveDbRuntime(envName) {
+    const runtime = await resolveManagedAppRuntime(envName);
+    if (!runtime) {
+        return undefined;
+    }
+    const source = runtime.kind === 'remote' ? 'remote' : runtime.source;
+    const dbDialect = String(runtime.env.config.dbDialect ?? 'postgres').trim() || 'postgres';
+    if (runtime.kind !== 'remote' && runtime.env.config.builtinDb) {
+        const containerName = buildDockerDbContainerName(runtime.envName, dbDialect, runtime.workspaceName);
+        return {
+            kind: 'builtin',
+            envName: runtime.envName,
+            source,
+            dbDialect,
+            containerName,
+            address: formatAddress(runtime.env.config.dbHost, runtime.env.config.dbPort, containerName),
+            appRuntime: runtime,
+        };
+    }
+    return {
+        kind: 'external',
+        envName: runtime.envName,
+        source,
+        dbDialect,
+        address: formatAddress(runtime.env.config.dbHost, runtime.env.config.dbPort),
+        status: runtime.kind === 'remote' ? 'remote' : 'external',
+        appRuntime: runtime,
+    };
+}
+export async function builtinDbStatus(containerName) {
+    if (!(await dockerContainerExists(containerName))) {
+        return 'missing';
+    }
+    return await dockerContainerIsRunning(containerName) ? 'running' : 'stopped';
+}
+export function formatUnmanagedDbMessage(action, runtime) {
+    const verb = action === 'start' ? 'start' : 'stop';
+    if (runtime.appRuntime.kind === 'remote') {
+        return [
+            `Can't ${verb} the database for "${runtime.envName}" from this machine.`,
+            'This env only has an API connection, so there is no CLI-managed database container here.',
+            'If you need CLI-managed database start and stop, create a local env with the built-in database option enabled.',
+        ].join('\n');
+    }
+    return [
+        `Can't ${verb} the database for "${runtime.envName}" from this machine.`,
+        'This env does not use a CLI-managed built-in database, so there is no saved database container to manage here.',
+        'If you need CLI-managed database start and stop, recreate the env with the built-in database option enabled.',
+    ].join('\n');
+}
+export function formatUnmanagedDbLogsMessage(runtime) {
+    if (runtime.appRuntime.kind === 'remote') {
+        return [
+            `Can't show database logs for "${runtime.envName}" from this machine.`,
+            'This env only has an API connection, so there is no CLI-managed database container here.',
+            'If you need CLI-managed database logs, create a local env with the built-in database option enabled.',
+        ].join('\n');
+    }
+    return [
+        `Can't show database logs for "${runtime.envName}" from this machine.`,
+        'This env does not use a CLI-managed built-in database, so there is no saved database container to read logs from here.',
+        'If you need CLI-managed database logs, recreate the env with the built-in database option enabled.',
+    ].join('\n');
+}