@ranger1/dx 0.1.3 → 0.1.4

package/README.md

@@ -2,6 +2,8 @@
 
 一个可安装的 Node.js CLI，用于管理符合约定的 pnpm + nx monorepo 项目的构建/启动/数据库/部署等流程。
 
+本工具通过项目内的 `dx/config/*` 配置文件来驱动命令执行：你可以把它理解成「带环境变量分层 + 校验 + 命令编排能力的脚本系统」。
+
 ## 安装
 
 全局安装（推荐）：
@@ -24,6 +26,16 @@ pnpm add -D @ranger1/dx
 pnpm exec dx --help
 ```
 
+## 使用条件（必须满足）
+
+- Node.js：>= 20
+- 包管理器：pnpm（dx 内部会调用 `pnpm`）
+- 构建系统：Nx（dx 默认命令配置里大量使用 `npx nx ...`）
+- 环境加载：建议项目依赖 `dotenv-cli`（dx 会用 `pnpm exec dotenv ...` 包裹命令来注入 `.env.*`）
+- 项目结构：默认按 `apps/backend` / `apps/front` / `apps/admin-front` / `apps/sdk` 这类布局编写命令配置
+
+如果你的 monorepo 不完全一致，也能用：关键是你在 `dx/config/commands.json` 里把命令写成适配你项目的形式。
+
 ## 项目配置（必须）
 
 dx 会从当前目录向上查找 `dx/config/commands.json` 来定位项目根目录。
@@ -47,6 +59,86 @@ dx/
 
 全局安装场景下，如果你不在项目目录内执行，也可以通过 `DX_CONFIG_DIR` / `--config-dir` 显式指定配置目录（目录下需要存在 `commands.json`）。
 
+示例：
+
+```bash
+# 在任意目录执行
+dx --config-dir /path/to/your-repo/dx/config status
+
+# 或
+DX_CONFIG_DIR=/path/to/your-repo/dx/config dx status
+```
+
+## 配置文件写法
+
+### 1) dx/config/commands.json
+
+这是核心文件，定义了 dx 各命令要执行的 shell 命令，支持：
+
+- 单命令：`{ "command": "..." }`
+- 并发：`{ "concurrent": true, "commands": ["build.front.dev", "build.admin.dev"] }`
+- 串行：`{ "sequential": true, "commands": ["build.backend.prod", "build.sdk"] }`
+- 环境分支：如 `build.backend.dev` / `build.backend.prod`（dx 会根据 `--dev/--prod/--staging/...` 选择）
+- dotenv 包裹：配置里带 `"app": "backend"` 时，dx 会按 `env-layers.json` 拼出 dotenv 层并用 `pnpm exec dotenv ... -- <command>` 执行
+
+常见字段（单命令配置）：
+
+```jsonc
+{
+  "command": "npx nx build backend --configuration=production",
+  "app": "backend",                // 可选：用于选择 dotenv 层，并决定需要校验的 env 变量组
+  "ports": [3000],                  // 可选：用于 start 类命令，冲突时自动清理
+  "description": "构建后端(生产环境)",
+  "dangerous": true,                // 可选：危险操作需要确认
+  "skipEnvValidation": true,         // 可选：跳过 env 校验（仍可加载 dotenv 层）
+  "env": { "NX_CACHE": "false" } // 可选：注入额外环境变量
+}
+```
+
+命令路径引用（并发/串行的 commands 数组）使用点号字符串，例如：
+
+```json
+{ "concurrent": true, "commands": ["build.shared", "build.front.dev"] }
+```
+
+### 2) dx/config/env-layers.json
+
+用于定义不同环境下加载哪些 `.env.*` 文件（顺序 = 覆盖优先级）。格式：
+
+```json
+{
+  "development": [".env.development", ".env.development.local"],
+  "staging": [".env.staging", ".env.staging.local"],
+  "production": [".env.production", ".env.production.local"],
+  "test": [".env.test", ".env.test.local"],
+  "e2e": [".env.e2e", ".env.e2e.local"]
+}
+```
+
+### 3) dx/config/required-env.jsonc
+
+用于定义哪些环境变量是「必须存在」的（dx 会在执行命令前校验）。它是 jsonc（允许 // 注释）。
+
+dx 的校验分组逻辑：
+
+- `_common`: 所有命令都会校验
+- `backend`: 当命令配置里 `app` 是 `backend` 时会校验
+- `frontend`: 当命令配置里 `app` 是 `front`/`admin-front` 等前端应用时会校验
+- `development`/`production`/`staging`/`test`/`e2e`: 按当前环境额外补充
+
+### 4) dx/config/local-env-allowlist.jsonc + exempted-keys.jsonc
+
+这是为了防止误提交机密：
+
+- `local-env-allowlist.jsonc`：允许出现在 `.env.*.local` 里的键（这些被认为是“机密”）
+- `exempted-keys.jsonc`：豁免键（允许在非 local 文件中出现真实值）
+
+非 local 的 `.env.*` 文件里，机密键必须使用占位符：`__SET_IN_env.local__`。
+
+## 示例工程
+
+查看 `example/`：包含一个最小可读的 `dx/config` 配置示例，以及如何在一个 pnpm+nx monorepo 中接入 dx。
+
 ## 命令
 
 dx 的命令由 `dx/config/commands.json` 驱动，并且内置了一些 internal runner（避免项目侧依赖任何 `scripts/lib/*.js`）：
@@ -101,4 +193,3 @@ dx test e2e backend
 ```bash
 npm publish --access public --registry=https://registry.npmjs.org
 ```
-

package/lib/cli/commands/contracts.js

@@ -0,0 +1,60 @@
+import { existsSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { logger } from '../../logger.js'
+import { execManager } from '../../exec.js'
+
+export async function handleContracts(cli, args = []) {
+  const action = args[0] || 'generate'
+  if (!['generate', 'pull'].includes(action)) {
+    logger.error(`不支持的 contracts 子命令: ${action}`)
+    logger.info(`用法: ${cli.invocation} contracts [generate|pull]`)
+    process.exitCode = 1
+    return
+  }
+
+  cli.ensureRepoRoot()
+
+  // starmomo/ai-monorepo compatibility: packages/api-contracts is expected
+  const contractsRoot = join(process.cwd(), 'packages', 'api-contracts')
+  if (!existsSync(contractsRoot)) {
+    logger.error(`未找到 contracts 目录: ${contractsRoot}`)
+    logger.info('期望存在 packages/api-contracts，用于输出生成的 Zod 合约。')
+    process.exitCode = 1
+    return
+  }
+
+  logger.step('导出 OpenAPI 并生成 Zod 合约')
+
+  // 1) Export OpenAPI spec to dist/openapi/backend.json
+  await execManager.executeCommand('npx nx run backend:swagger', {
+    app: 'backend',
+    flags: cli.flags,
+    env: { NX_CACHE: 'false', SKIP_PRISMA_CONNECT: 'true' },
+  })
+
+  // 2) Generate zod client
+  const outputDir = join(contractsRoot, 'src', 'generated')
+  mkdirSync(outputDir, { recursive: true })
+
+  const baseUrl = process.env.OPENAPI_BASE_URL || 'http://localhost:3000/api/v1'
+  logger.info(`使用 API 基地址: ${baseUrl}`)
+
+  const generatorCommand = [
+    'pnpm exec openapi-zod-client',
+    'dist/openapi/backend.json',
+    '--output packages/api-contracts/src/generated/backend.ts',
+    '--api-client-name aiBackendClient',
+    `--base-url "${baseUrl}"`,
+    '--with-alias',
+    '--with-docs',
+    '--with-deprecated',
+    '--export-schemas',
+    '--prettier prettier.config.js',
+  ].join(' ')
+
+  await execManager.executeCommand(generatorCommand, {
+    flags: cli.flags,
+  })
+
+  logger.success('Zod 合约已更新（packages/api-contracts）')
+}

package/lib/cli/commands/release.js

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { logger } from '../../logger.js'
+
+export async function handleRelease(cli, args = []) {
+  const action = args[0]
+  const version = args[1]
+
+  if (action !== 'version') {
+    logger.error(`用法: ${cli.invocation} release version <版本号>`)
+    process.exitCode = 1
+    return
+  }
+
+  if (!version) {
+    logger.error(`请提供要发布的版本号，例如: ${cli.invocation} release version 1.2.3`)
+    process.exitCode = 1
+    return
+  }
+
+  cli.ensureRepoRoot()
+
+  const semverPattern = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/
+  if (!semverPattern.test(version)) {
+    logger.warn(`版本号 ${version} 不符合常见语义化版本格式，仍将继续更新`)
+  }
+
+  const packageFiles = [
+    'apps/backend/package.json',
+    'apps/front/package.json',
+    'apps/admin-front/package.json',
+  ]
+
+  logger.step(`统一更新版本号 -> ${version}`)
+
+  for (const relativePath of packageFiles) {
+    const fullPath = join(process.cwd(), relativePath)
+    if (!existsSync(fullPath)) {
+      logger.warn(`跳过，未找到文件: ${relativePath}`)
+      continue
+    }
+
+    try {
+      const raw = readFileSync(fullPath, 'utf8')
+      const pkg = JSON.parse(raw)
+      const previous = pkg.version || '0.0.0'
+      pkg.version = version
+      writeFileSync(fullPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8')
+      logger.info(`更新 ${relativePath}: ${previous} -> ${version}`)
+    } catch (error) {
+      logger.error(`更新 ${relativePath} 失败: ${error?.message || String(error)}`)
+    }
+  }
+
+  logger.success(`版本号已同步为 ${version}`)
+}

package/lib/cli/dx-cli.js

@@ -26,6 +26,8 @@ import { handleDatabase } from './commands/db.js'
 import { handleWorktree } from './commands/worktree.js'
 import { handlePackage } from './commands/package.js'
 import { handleExport } from './commands/export.js'
+import { handleContracts } from './commands/contracts.js'
+import { handleRelease } from './commands/release.js'
 
 class DxCli {
   constructor(options = {}) {
@@ -58,6 +60,8 @@ class DxCli {
       worktree: args => handleWorktree(this, args),
       package: args => handlePackage(this, args),
       export: args => handleExport(this, args),
+      contracts: args => handleContracts(this, args),
+      release: args => handleRelease(this, args),
     }
 
     this.flagDefinitions = FLAG_DEFINITIONS
@@ -277,10 +281,21 @@ class DxCli {
         return
       }
 
+      this.validateInputs()
+
+      // Commands that should work without env/dependency checks.
+      // - help: printing help should never require env vars.
+      // - status: should be available even when env is incomplete.
+      // - release: only edits package.json versions.
+      const skipStartupChecks = new Set(['help', 'status', 'release'])
+      if (skipStartupChecks.has(this.command)) {
+        await this.routeCommand()
+        return
+      }
+
       // 在执行命令前先校验参数与选项
       await this.ensureDependencies()
       await this.runStartupChecks()
-      this.validateInputs()
 
       // 设置详细模式
       if (this.flags.verbose) {

package/lib/cli/help.js

@@ -55,6 +55,10 @@ DX CLI v${version} - 统一开发环境管理工具
 
   lint                   运行代码检查
 
+  contracts [generate]       导出后端 OpenAPI 并生成 Zod 合约（packages/api-contracts）
+
+  release version <semver>   统一同步 backend/front/admin-front 的版本号
+
   clean [target]         清理操作
     target: all, deps (默认: all)
 
@@ -93,6 +97,8 @@ DX CLI v${version} - 统一开发环境管理工具
   dx worktree list          # 列出所有worktree
   dx clean deps             # 清理并重新安装依赖
   dx cache clear            # 清除 Nx 与依赖缓存
+  dx contracts              # 导出 OpenAPI 并生成 Zod 合约
+  dx release version 1.2.3  # 同步 backend/front/admin-front 版本号
 
   # Stagewise 桥接（固定端口，自动清理占用）
   dx start stagewise-front      # 桥接 front: 3001 -> 3002（工作目录 apps/front）
@@ -204,6 +210,41 @@ start 命令用法:
   dx start stagewise-front      # Stagewise 桥接用户前端，端口 3001 -> 3002
 
 提示: service 省略时默认启动 dev 套件，可结合 --dev/--staging/--prod 标志使用。
+`)
+      return
+
+    case 'contracts':
+      console.log(`
+contracts 命令用法:
+  dx contracts [generate|pull]
+
+说明:
+  1) 先运行: npx nx run backend:swagger
+  2) 再运行: openapi-zod-client 生成 packages/api-contracts/src/generated/backend.ts
+
+环境变量:
+  OPENAPI_BASE_URL  默认: http://localhost:3000/api/v1
+
+示例:
+  dx contracts
+  OPENAPI_BASE_URL="https://api.example.com/api/v1" dx contracts
+`)
+      return
+
+    case 'release':
+      console.log(`
+release 命令用法:
+  dx release version <semver>
+
+说明:
+  同步更新以下 package.json 的 version 字段（存在则更新，不存在则跳过）：
+  - apps/backend/package.json
+  - apps/front/package.json
+  - apps/admin-front/package.json
+
+示例:
+  dx release version 1.2.3
+  dx release version 1.2.3-beta.1
 `)
       return
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ranger1/dx",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "license": "MIT",
   "repository": {