@ranger1/dx 0.1.9 → 0.1.10

package/README.md

@@ -6,10 +6,10 @@
 
 ## 安装
 
-全局安装（推荐）：
+必须全局安装，并始终使用最新版本：
 
 ```bash
-pnpm add -g @ranger1/dx
+pnpm add -g @ranger1/dx@latest
 ```
 
 安装后即可在任意目录使用：
@@ -19,11 +19,10 @@ dx --help
 dx status
 ```
 
-项目内安装（可选，如果你更希望锁定版本）：
+升级到最新版本：
 
 ```bash
-pnpm add -D @ranger1/dx
-pnpm exec dx --help
+pnpm update -g @ranger1/dx
 ```
 
 ## 使用条件（必须满足）
@@ -32,7 +31,7 @@ pnpm exec dx --help
 - 包管理器：pnpm（dx 内部会调用 `pnpm`）
 - 构建系统：Nx（dx 默认命令配置里大量使用 `npx nx ...`）
 - 环境加载：建议项目依赖 `dotenv-cli`（dx 会用 `pnpm exec dotenv ...` 包裹命令来注入 `.env.*`）
-- 项目结构：默认按 `apps/backend` / `apps/front` / `apps/admin-front` / `apps/sdk` 这类布局编写命令配置
+- 项目结构：推荐按 `apps/backend` / `apps/front` / `apps/admin-front` 这类布局组织；如有自定义目录结构，请通过 `dx/config/commands.json` 适配
 
 如果你的 monorepo 不完全一致，也能用：关键是你在 `dx/config/commands.json` 里把命令写成适配你项目的形式。
 
@@ -123,7 +122,7 @@ DX_CONFIG_DIR=/path/to/your-repo/dx/config dx status
 
 target（端）不写死，由 `env-policy.jsonc.targets` 定义；`commands.json` 里的 `app` 通过 `env-policy.jsonc.appToTarget` 映射到某个 target。
 
-注：若未提供 `env-policy.jsonc`，dx 会继续使用旧的 `required-env.jsonc` / `local-env-allowlist.jsonc` / `exempted-keys.jsonc` 逻辑（兼容模式）。
+注：`env-policy.jsonc` 为必需配置；未提供时 dx 将直接报错。
 
 ## 示例工程
 
@@ -159,6 +158,15 @@ dx test e2e backend
 - 需要的前置构建（例如 `shared`、`api-contracts`、OpenAPI 导出、后端构建等）应由项目自己的 Nx 依赖图（`dependsOn`/项目依赖）或 Vercel 的 `buildCommand` 负责。
 - 这样 dx deploy 不会强依赖 `apps/sdk` 等目录结构，更容易适配不同 monorepo。
 
+## 依赖关系约定
+
+dx 不负责管理「工程之间的构建依赖关系」。如果多个工程之间存在依赖（例如 `front/admin` 依赖 `shared` 或 `api-contracts`），必须由 Nx 的依赖图来表达并自动拉起：
+
+- 使用 Nx 的项目依赖（基于 import graph 或 `implicitDependencies`）
+- 使用 `nx.json` 的 `targetDefaults.dependsOn` / `targetDependencies`
+
+dx 只会执行你在 `dx/config/commands.json` 中配置的命令，不会在执行过程中额外硬编码插入依赖构建。
+
 ## 给 Nx target 注入版本信息（可选）
 
 本包提供 `dx-with-version-env`，用于在 `nx:run-commands` 中注入版本/sha/构建时间等环境变量：
@@ -176,7 +184,7 @@ dx test e2e backend
 当前版本面向 pnpm + nx 的 monorepo，默认假设：
 
 - 使用 pnpm + nx
-- 项目布局包含 `apps/backend`、`apps/front`、`apps/admin-front`、`apps/sdk`（如果你的命令配置不依赖这些目录，可自行调整）
+- 项目布局包含 `apps/backend`、`apps/front`、`apps/admin-front`（如有差异，通过 `dx/config/commands.json` 适配）
 - 版本注入脚本 `dx-with-version-env` 默认支持 app: `backend` / `front` / `admin`
 
 ## 发布到 npm（准备工作）

package/lib/backend-package.js

@@ -239,18 +239,11 @@ class BackendPackager {
   async prepareEnvSnapshot() {
     logger.info('校验并快照环境变量')
     const policy = loadEnvPolicy(envManager.configDir)
-    let requiredVars = []
-    if (policy) {
-      const targetId = resolvePolicyTargetId(policy, 'backend')
-      if (!targetId) {
-        throw new Error(
-          'env-policy.jsonc 已启用，但缺少 appToTarget.backend 配置（dx 内置逻辑需要 backend target）',
-        )
-      }
-      requiredVars = resolveTargetRequiredVars(policy, targetId, this.layerEnv)
-    } else {
-      requiredVars = envManager.getRequiredEnvVars(this.layerEnv, 'backend')
+    const targetId = resolvePolicyTargetId(policy, 'backend')
+    if (!targetId) {
+      throw new Error('缺少 appToTarget.backend 配置（dx 内置逻辑需要 backend target）')
     }
+    const requiredVars = resolveTargetRequiredVars(policy, targetId, this.layerEnv)
     const collected = envManager.collectEnvFromLayers('backend', this.layerEnv)
     const effectiveEnv = { ...collected, ...process.env }
     const { valid, missing, placeholders } = envManager.validateRequiredVars(

package/lib/cli/dx-cli.js

@@ -221,18 +221,11 @@ class DxCli {
       if (process.env.CI !== '1') {
         const effectiveEnv = { ...process.env, ...layeredEnv }
         const policy = loadEnvPolicy(envManager.configDir)
-        let requiredVars = []
-        if (policy) {
-          const targetId = resolvePolicyTargetId(policy, 'backend')
-          if (!targetId) {
-            throw new Error(
-              'env-policy.jsonc 已启用，但缺少 appToTarget.backend 配置（dx 内置逻辑需要 backend target）',
-            )
-          }
-          requiredVars = resolveTargetRequiredVars(policy, targetId, environment)
-        } else {
-          requiredVars = envManager.getRequiredEnvVars(environment, 'backend')
+        const targetId = resolvePolicyTargetId(policy, 'backend')
+        if (!targetId) {
+          throw new Error('缺少 appToTarget.backend 配置（dx 内置逻辑需要 backend target）')
         }
+        const requiredVars = resolveTargetRequiredVars(policy, targetId, environment)
         if (requiredVars.length > 0) {
           const { valid, missing, placeholders } = envManager.validateRequiredVars(
             requiredVars,

package/lib/env-policy.js

@@ -28,9 +28,11 @@ export function loadEnvPolicy(configDir) {
 
   const policyPath = join(configDir, DEFAULT_POLICY_PATH)
   if (!existsSync(policyPath)) {
-    cachedPolicy = null
-    cachedPolicyDir = configDir
-    return null
+    throw new Error(
+      `缺少配置文件 ${DEFAULT_POLICY_PATH}。
+请在目标工程根目录创建 dx/config/${DEFAULT_POLICY_PATH}（或用 DX_CONFIG_DIR / --config-dir 指定配置目录）。
+当前配置目录: ${configDir}`,
+    )
   }
 
   let parsed

package/lib/env.js

@@ -1,6 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
-import stripJsonComments from 'strip-json-comments'
 
 function resolveProjectRoot() {
   return process.env.DX_PROJECT_ROOT || process.cwd()
@@ -16,7 +15,6 @@ export class EnvManager {
     this.projectRoot = resolveProjectRoot()
     this.configDir = resolveConfigDir()
     this.envLayers = this.loadEnvLayers()
-    this.requiredEnvConfig = null
     this.latestEnvWarnings = []
 
     // APP_ENV → NODE_ENV 映射（用于运行时行为和工具链，如 Nx/Next）
@@ -103,43 +101,6 @@ export class EnvManager {
     return layers.map(layer => layer.replace('{app}', app))
   }
 
-  loadRequiredEnvConfig() {
-    if (this.requiredEnvConfig) return this.requiredEnvConfig
-    const configPath = join(this.configDir, 'required-env.jsonc')
-    if (!existsSync(configPath)) {
-      this.requiredEnvConfig = { _common: [] }
-      return this.requiredEnvConfig
-    }
-
-    try {
-      const raw = readFileSync(configPath, 'utf8')
-      const sanitized = stripJsonComments(raw)
-      this.requiredEnvConfig = JSON.parse(sanitized || '{}') || { _common: [] }
-    } catch (error) {
-      throw new Error(`无法解析 required-env.jsonc: ${error.message}`)
-    }
-    return this.requiredEnvConfig
-  }
-
-  getRequiredEnvVars(environment, appType = null) {
-    const config = this.loadRequiredEnvConfig()
-    const base = Array.isArray(config._common) ? config._common : []
-    const envSpecific = Array.isArray(config[environment]) ? config[environment] : []
-
-    // 按应用类型添加对应的环境变量组
-    let appSpecific = []
-    if (appType) {
-      const appTypes = Array.isArray(appType) ? appType : [appType]
-      for (const type of appTypes) {
-        if (Array.isArray(config[type])) {
-          appSpecific = appSpecific.concat(config[type])
-        }
-      }
-    }
-
-    return Array.from(new Set([...base, ...envSpecific, ...appSpecific]))
-  }
-
   // 构建dotenv命令参数
   buildEnvFlags(app, environment) {
     return this.getResolvedEnvLayers(app, environment)

package/lib/exec.js

@@ -80,7 +80,7 @@ export class ExecManager {
        const policy = loadEnvPolicy(envManager.configDir)
        let requiredVars = []
 
-       if (!isCI && policy && app) {
+       if (!isCI && app) {
          const targetId = resolvePolicyTargetId(policy, app)
          if (!targetId) {
            throw new Error(
@@ -88,12 +88,6 @@ export class ExecManager {
            )
          }
          requiredVars = resolveTargetRequiredVars(policy, targetId, environment)
-       } else if (!policy) {
-         // Backward-compatible behavior
-         // CI 环境跳过后端环境变量校验（CI 中 build backend 只生成 OpenAPI，不需要数据库连接）
-         // 根据 app 参数确定需要检查的环境变量组
-         const appType = isCI ? null : (app === 'backend' ? 'backend' : app ? 'frontend' : null)
-         requiredVars = envManager.getRequiredEnvVars(environment, appType)
        }
 
        if (requiredVars.length > 0) {

package/lib/validate-env.js

@@ -16,21 +16,7 @@ const EXTRA_ENV_IGNORED_DIRS = new Set([
   '.schaltwerk',
 ])
 const EXTRA_ENV_ALLOWED_PATHS = new Set(['docker/.env', 'docker/.env.example'])
-const LOCAL_ALLOWLIST_CONFIG = join(CONFIG_DIR, 'local-env-allowlist.jsonc')
-const EXEMPTED_KEYS_CONFIG = join(CONFIG_DIR, 'exempted-keys.jsonc')
 const ENV_EXAMPLE_FILE = join(ROOT_DIR, '.env.example')
-const PLACEHOLDER_TOKEN = '__SET_IN_env.local__'
-
-const LOCAL_ENV_FILES = [
-  '.env.development.local',
-  '.env.production.local',
-  '.env.test.local',
-  '.env.e2e.local',
-  '.env.staging.local',
-]
-
-let cachedAllowlist = null
-let cachedExemptedKeys = null
 
 export function validateEnvironment() {
   if (!process.env.NODE_ENV) {
@@ -47,15 +33,8 @@ export function validateEnvironment() {
   enforceRootOnlyEnvFiles(policy)
   enforceGlobalLocalFileProhibited()
 
-  if (policy) {
-    enforceSecretPolicy(policy)
-    enforceEnvExamplePolicy(policy)
-  } else {
-    // Backward-compatible behavior
-    enforceLocalSecretWhitelist()
-    enforceNonLocalSecretPlaceholders()
-    enforceEnvExampleSecrets()
-  }
+  enforceSecretPolicy(policy)
+  enforceEnvExamplePolicy(policy)
 
   return { nodeEnv: process.env.NODE_ENV, appEnv: process.env.APP_ENV }
 }
@@ -114,36 +93,6 @@ function enforceRootOnlyEnvFiles(policy) {
   }
 }
 
-function enforceLocalSecretWhitelist() {
-  const allowlist = loadLocalAllowlist()
-  const errors = []
-
-  for (const file of LOCAL_ENV_FILES) {
-    const fullPath = join(ROOT_DIR, file)
-    if (!existsSync(fullPath)) continue
-
-    const entries = parseEnvFile(fullPath)
-    const invalidKeys = []
-
-    for (const key of entries.keys()) {
-      if (!allowlist.has(key)) {
-        invalidKeys.push(key)
-      }
-    }
-
-    if (invalidKeys.length > 0) {
-      errors.push(`${file}: ${invalidKeys.join(', ')}`)
-    }
-  }
-
-  if (errors.length > 0) {
-    const message = errors.join('\n')
-    throw new Error(
-      `检测到 *.local 文件包含非白名单键:\n${message}\n请将这些键迁移到对应的 .env.<env> 文件，仅保留白名单内的机密信息在 *.local 中。`,
-    )
-  }
-}
-
 function enforceGlobalLocalFileProhibited() {
   const legacyLocal = join(ROOT_DIR, '.env.local')
   if (existsSync(legacyLocal)) {
@@ -320,80 +269,6 @@ function findOverlaps(namedSets) {
   return overlaps
 }
 
-function enforceNonLocalSecretPlaceholders() {
-  const allowlist = loadLocalAllowlist()
-  const exemptedKeys = loadExemptedKeys()
-  const violations = []
-
-  for (const file of listRootEnvFiles()) {
-    if (file === '.env.example') continue
-    if (file.includes('.local')) continue
-
-    const fullPath = join(ROOT_DIR, file)
-    if (!existsSync(fullPath)) continue
-
-    const entries = parseEnvFile(fullPath)
-
-    for (const [key, value] of entries.entries()) {
-      if (!allowlist.has(key)) continue
-      if (exemptedKeys.has(key)) continue // 豁免的键允许使用非占位符值
-
-      const normalized = value.trim()
-      if (normalized !== PLACEHOLDER_TOKEN) {
-        violations.push(`${file}: ${key}`)
-      }
-    }
-  }
-
-  if (violations.length > 0) {
-    const message = violations.join('\n')
-    throw new Error(
-      `检测到非 *.local 文件包含敏感键但未使用占位符 ${PLACEHOLDER_TOKEN}:\n${message}\n` +
-        `请仅在 .env.<env>.local 系列中设置真实值，并在其他文件中使用占位符。`,
-    )
-  }
-}
-
-function enforceEnvExampleSecrets() {
-  if (!existsSync(ENV_EXAMPLE_FILE)) return
-
-  const allowlist = loadLocalAllowlist()
-  const entries = parseEnvFile(ENV_EXAMPLE_FILE)
-  const disallowedKeys = []
-  const invalidPlaceholders = []
-
-  for (const [key, value] of entries.entries()) {
-    const normalized = value.trim()
-
-    if (!allowlist.has(key)) {
-      disallowedKeys.push(key)
-      continue
-    }
-
-    if (normalized !== PLACEHOLDER_TOKEN) {
-      invalidPlaceholders.push(key)
-    }
-  }
-
-  if (disallowedKeys.length > 0) {
-    throw new Error(
-      `.env.example 仅允许包含 scripts/config/local-env-allowlist.jsonc 中的键，检测到非法键: ${disallowedKeys.join(', ')}`,
-    )
-  }
-
-  if (invalidPlaceholders.length > 0) {
-    throw new Error(
-      `.env.example 中以下键未使用占位符 ${PLACEHOLDER_TOKEN}: ${invalidPlaceholders.join(', ')}`,
-    )
-  }
-}
-
-function listRootEnvFiles() {
-  return readdirSync(ROOT_DIR, { withFileTypes: true })
-    .filter(entry => entry.isFile() && entry.name.startsWith('.env'))
-    .map(entry => entry.name)
-}
-
 function parseEnvFile(filePath) {
   const content = readFileSync(filePath, 'utf8')
   const map = new Map()
@@ -415,57 +290,4 @@ function parseEnvFile(filePath) {
   return map
 }
 
-function loadLocalAllowlist() {
-  if (cachedAllowlist) return cachedAllowlist
-
-  if (!existsSync(LOCAL_ALLOWLIST_CONFIG)) {
-    throw new Error('缺少配置文件 scripts/config/local-env-allowlist.jsonc，请补充后重试')
-  }
-
-  const raw = readFileSync(LOCAL_ALLOWLIST_CONFIG, 'utf8')
-  const sanitized = raw.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '')
-  const parsed = JSON.parse(sanitized || '{}') || {}
-
-  const allowedValues = Array.isArray(parsed.allowed) ? parsed.allowed : []
-  if (allowedValues.length === 0) {
-    throw new Error('local-env-allowlist.jsonc 中的 allowed 不能为空，请至少保留一个键')
-  }
-
-  const invalid = allowedValues.filter(
-    value => typeof value !== 'string' || value.trim().length === 0,
-  )
-  if (invalid.length > 0) {
-    throw new Error('local-env-allowlist.jsonc.allowed 中存在非法键，请使用非空字符串')
-  }
-
-  cachedAllowlist = new Set(allowedValues)
-  return cachedAllowlist
-}
-
-function loadExemptedKeys() {
-  if (cachedExemptedKeys) return cachedExemptedKeys
-
-  // 如果豁免配置文件不存在，返回空集合（可选配置）
-  if (!existsSync(EXEMPTED_KEYS_CONFIG)) {
-    cachedExemptedKeys = new Set()
-    return cachedExemptedKeys
-  }
-
-  const raw = readFileSync(EXEMPTED_KEYS_CONFIG, 'utf8')
-  const sanitized = raw.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '')
-  const parsed = JSON.parse(sanitized || '{}') || {}
-
-  const exemptedValues = Array.isArray(parsed.exempted) ? parsed.exempted : []
-  
-  const invalid = exemptedValues.filter(
-    value => typeof value !== 'string' || value.trim().length === 0,
-  )
-  if (invalid.length > 0) {
-    throw new Error('exempted-keys.jsonc.exempted 中存在非法键，请使用非空字符串')
-  }
-
-  cachedExemptedKeys = new Set(exemptedValues)
-  return cachedExemptedKeys
-}
-
 export default { validateEnvironment }

package/package.json

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