@nocobase/cli 2.1.0-beta.2 → 2.1.0-beta.21

package/README.zh-CN.md

@@ -0,0 +1,336 @@
+# 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 restart` | 先停止，再启动选中的本地应用或 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 restart --env app1
+nb logs --env app1
+nb ps --env app1
+nb db ps --env app1
+```
+
+等价的简写示例：
+
+```bash
+nb start -e app1
+nb restart -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 restart --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 --api-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.cmd

@@ -0,0 +1,3 @@
+@echo off
+
+node "%~dp0\run" %*

package/bin/run.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+
+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');
+let isDev = isSourcePackage;
+if (process.env.NB_CLI_USE_DIST === '1') {
+  isDev = false;
+}
+
+/**
+ * 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 reexecArgs = ['--import', pathToFileURL(tsxEntry).href];
+  const supportedFlags = Array.from(process.allowedNodeEnvironmentFlags);
+  if (supportedFlags.some((flag) => flag === '--disable-warning' || flag.startsWith('--disable-warning='))) {
+    reexecArgs.push('--disable-warning=ExperimentalWarning');
+  }
+
+  const result = spawnSync(process.execPath, [...reexecArgs, ...process.argv.slice(1)], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      _NOCO_CLI_TSX_CHILD: '1',
+      NODE_ENV: 'development',
+    },
+  });
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+if (isDev && !process.env._NOCO_CLI_TSX_CHILD) {
+  reexecWithTsx();
+}
+
+const bootstrapPath = isDev ? path.join(root, 'src/lib/bootstrap.ts') : path.join(root, 'dist/lib/bootstrap.js');
+const { ensureRuntimeFromArgv } = await import(pathToFileURL(bootstrapPath).href);
+const startupUpdatePath = isDev
+  ? path.join(root, 'src/lib/startup-update.ts')
+  : path.join(root, 'dist/lib/startup-update.js');
+const { maybeRunStartupUpdatePrompt } = await import(pathToFileURL(startupUpdatePath).href);
+const { flush, run, settings } = await import('@oclif/core');
+
+if (isDev) {
+  settings.debug = true;
+}
+
+function getCommandToken(argv) {
+  const tokens = [];
+
+  for (const token of argv) {
+    if (!token || token.startsWith('-')) {
+      continue;
+    }
+
+    tokens.push(token);
+  }
+
+  if (tokens[0] === 'api') {
+    return tokens[1] ?? tokens[0];
+  }
+
+  return tokens[0];
+}
+
+function formatCliEntryError(error, argv) {
+  const message = error instanceof Error ? error.message : String(error);
+  const missingCommandMatch = message.match(/^Command (.+) not found\.$/);
+  if (missingCommandMatch) {
+    const commandToken = getCommandToken(argv) ?? missingCommandMatch[1];
+    return [
+      `Unknown command: \`${commandToken}\`.`,
+      'If this is a built-in command or a typo, run `nb --help` to inspect available commands.',
+      `If \`${commandToken}\` should be a runtime command from your NocoBase app, run \`nb env update\` and try again.`,
+    ].join('\n');
+  }
+
+  return message;
+}
+
+try {
+  const argv = process.argv.slice(2);
+  const startupUpdate = await maybeRunStartupUpdatePrompt(argv);
+  if (startupUpdate.kind === 'updated') {
+    const result = spawnSync(process.execPath, process.argv.slice(1), {
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        NB_SKIP_STARTUP_UPDATE: '1',
+      },
+    });
+    process.exit(result.status === null ? 1 : result.status);
+  }
+  if (argv[0] === 'api') {
+    await ensureRuntimeFromArgv(argv, {
+      configFile: path.join(root, 'nocobase-ctl.config.json'),
+    });
+  }
+  await run(argv, import.meta.url);
+  flush();
+} catch (error) {
+  const message = formatCliEntryError(error, process.argv.slice(2));
+  console.error(message);
+  process.exitCode = 1;
+}

package/dist/commands/api/resource/create.js

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+import { buildCreateArgs, createFlags, runResourceCommand } from '../../../lib/resource-command.js';
+export default class ResourceCreate extends Command {
+    static summary = 'Create a record in a resource';
+    static description = 'Create a record in a generic resource. Pass record content through --values as a JSON object.';
+    static examples = [
+        `<%= config.bin %> <%= command.id %> --resource users --values '{"nickname":"Ada"}'`,
+        `<%= config.bin %> <%= command.id %> --resource posts.comments --source-id 1 --values '{"content":"Hello"}'`,
+    ];
+    static flags = createFlags;
+    async run() {
+        const { flags } = await this.parse(ResourceCreate);
+        await runResourceCommand(this, 'create', flags, buildCreateArgs(flags));
+    }
+}

package/dist/commands/api/resource/destroy.js

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+import { buildDestroyArgs, destroyFlags, runResourceCommand } from '../../../lib/resource-command.js';
+export default class ResourceDestroy extends Command {
+    static summary = 'Delete records from a resource';
+    static description = 'Delete records from a generic resource. Target records with --filter-by-tk or --filter.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --resource users --filter-by-tk 1',
+        `<%= config.bin %> <%= command.id %> --resource posts --filter '{"status":"archived"}'`,
+    ];
+    static flags = destroyFlags;
+    async run() {
+        const { flags } = await this.parse(ResourceDestroy);
+        await runResourceCommand(this, 'destroy', flags, buildDestroyArgs(flags));
+    }
+}

package/dist/commands/api/resource/get.js

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+import { buildGetArgs, getFlags, runResourceCommand } from '../../../lib/resource-command.js';
+export default class ResourceGet extends Command {
+    static summary = 'Get a record from a resource';
+    static description = 'Get a record from a generic resource. Use --filter-by-tk for the primary key and association resource names with --source-id when needed.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --resource users --filter-by-tk 1',
+        '<%= config.bin %> <%= command.id %> --resource posts.comments --source-id 1 --filter-by-tk 2',
+    ];
+    static flags = getFlags;
+    async run() {
+        const { flags } = await this.parse(ResourceGet);
+        await runResourceCommand(this, 'get', flags, buildGetArgs(flags));
+    }
+}

package/dist/commands/api/resource/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 Resource extends Command {
+    static summary = 'Work with generic collection resources';
+    async run() {
+        await this.parse(Resource);
+        const Help = await loadHelpClass(this.config);
+        await new Help(this.config, this.config.pjson.oclif.helpOptions ?? this.config.pjson.helpOptions).showHelp([
+            this.id ?? 'api:resource',
+            ...this.argv,
+        ]);
+    }
+}

package/dist/commands/api/resource/list.js

@@ -0,0 +1,16 @@
+import { Command } from '@oclif/core';
+import { buildListArgs, listFlags, runResourceCommand } from '../../../lib/resource-command.js';
+export default class ResourceList extends Command {
+    static summary = 'List records from a resource';
+    static description = 'List records from a generic resource. Use association resource names like posts.comments with --source-id when needed.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --resource users',
+        '<%= config.bin %> <%= command.id %> --resource posts.comments --source-id 1 --fields id --fields content',
+        `<%= config.bin %> <%= command.id %> --resource users --filter '{"status":"active"}' --sort=-createdAt`,
+    ];
+    static flags = listFlags;
+    async run() {
+        const { flags } = await this.parse(ResourceList);
+        await runResourceCommand(this, 'list', flags, buildListArgs(flags));
+    }
+}

package/dist/commands/api/resource/query.js

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+import { buildQueryArgs, queryFlags, runResourceCommand } from '../../../lib/resource-command.js';
+export default class ResourceQuery extends Command {
+    static summary = 'Run an aggregate query on a resource';
+    static description = 'Run an aggregate query on a generic resource. Pass measures, dimensions, and orders as JSON arrays.';
+    static examples = [
+        `<%= config.bin %> <%= command.id %> --resource orders --measures '[{"field":["id"],"aggregation":"count","alias":"count"}]'`,
+        `<%= config.bin %> <%= command.id %> --resource orders --dimensions '[{"field":["status"],"alias":"status"}]' --orders '[{"field":["createdAt"],"order":"desc"}]'`,
+    ];
+    static flags = queryFlags;
+    async run() {
+        const { flags } = await this.parse(ResourceQuery);
+        await runResourceCommand(this, 'query', flags, buildQueryArgs(flags));
+    }
+}

package/dist/commands/api/resource/update.js

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+import { buildUpdateArgs, runResourceCommand, updateFlags } from '../../../lib/resource-command.js';
+export default class ResourceUpdate extends Command {
+    static summary = 'Update records in a resource';
+    static description = 'Update records in a generic resource. Target records with --filter-by-tk or --filter, and pass updated values through --values.';
+    static examples = [
+        `<%= config.bin %> <%= command.id %> --resource users --filter-by-tk 1 --values '{"nickname":"Grace"}'`,
+        `<%= config.bin %> <%= command.id %> --resource posts --filter '{"status":"draft"}' --values '{"status":"published"}'`,
+    ];
+    static flags = updateFlags;
+    async run() {
+        const { flags } = await this.parse(ResourceUpdate);
+        await runResourceCommand(this, 'update', flags, buildUpdateArgs(flags));
+    }
+}

package/dist/commands/build.js

@@ -0,0 +1,57 @@
+/**
+ * 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, 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. */
+        packages: Args.string({
+            description: 'package names to build',
+            multiple: true,
+            required: false,
+        }),
+    };
+    static description = 'Run the legacy NocoBase build (forwards to `npm run build` in the repo root)';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> --no-dts',
+        '<%= config.bin %> <%= command.id %> --sourcemap',
+        '<%= config.bin %> <%= command.id %> @nocobase/acl',
+        '<%= config.bin %> <%= command.id %> @nocobase/acl @nocobase/actions',
+    ];
+    static flags = {
+        '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']) {
+            npmArgs.push('--no-dts');
+        }
+        if (flags.sourcemap) {
+            npmArgs.push('--sourcemap');
+        }
+        try {
+            await runNocoBaseCommand(npmArgs, {
+                cwd: flags['cwd'],
+                stdio: flags.verbose ? 'inherit' : 'ignore',
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.error(message);
+        }
+    }
+}