@ranger1/dx 0.1.4 → 0.1.7

package/README.md

@@ -47,9 +47,7 @@ dx/
   config/
     commands.json
     env-layers.json
-    required-env.jsonc
-    local-env-allowlist.jsonc
-    exempted-keys.jsonc
+    env-policy.jsonc
 ```
 
 可选覆盖：
@@ -115,25 +113,17 @@ DX_CONFIG_DIR=/path/to/your-repo/dx/config dx status
 }
 ```
 
-### 3) dx/config/required-env.jsonc
+### 3) dx/config/env-policy.jsonc
 
-用于定义哪些环境变量是「必须存在」的（dx 会在执行命令前校验）。它是 jsonc（允许 // 注释）。
+统一的 env 策略配置（jsonc），同时覆盖：
 
-dx 的校验分组逻辑：
+- env 文件布局约束（禁用 `.env` / `.env.local`；禁止子目录散落 `.env*`，仅允许少数特例路径）
+- 机密键策略：机密 key 只能在 `.env.<env>.local` 放真实值；对应的 `.env.<env>` 必须存在同名 key 且为占位符 `__SET_IN_env.local__`
+- 必填校验：按环境 + 按 target（端）定义 required keys，执行命令前校验是否缺失/仍为占位符
 
-- `_common`: 所有命令都会校验
-- `backend`: 当命令配置里 `app` 是 `backend` 时会校验
-- `frontend`: 当命令配置里 `app` 是 `front`/`admin-front` 等前端应用时会校验
-- `development`/`production`/`staging`/`test`/`e2e`: 按当前环境额外补充
+target（端）不写死，由 `env-policy.jsonc.targets` 定义；`commands.json` 里的 `app` 通过 `env-policy.jsonc.appToTarget` 映射到某个 target。
 
-### 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__`。
+注：若未提供 `env-policy.jsonc`，dx 会继续使用旧的 `required-env.jsonc` / `local-env-allowlist.jsonc` / `exempted-keys.jsonc` 逻辑（兼容模式）。
 
 ## 示例工程
 

package/bin/dx.js

@@ -31,6 +31,33 @@ function stripConfigDirArgs(argv) {
   return out
 }
 
+function isVersionInvocation(argv) {
+  const raw = Array.isArray(argv) ? argv : []
+  const filtered = stripConfigDirArgs(raw)
+
+  const flags = []
+  const positionals = []
+  for (const token of filtered) {
+    if (token === '--') break
+    if (token.startsWith('-')) flags.push(token)
+    else positionals.push(token)
+  }
+
+  // Keep current semantics:
+  // - -V/--version always prints version and exits.
+  // - -v is verbose in commands, but `dx -v` is commonly expected to show version.
+  const hasCanonicalVersionFlag = flags.includes('-V') || flags.includes('--version')
+  if (hasCanonicalVersionFlag) return true
+
+  const isBareLowerV = flags.length === 1 && flags[0] === '-v' && positionals.length === 0
+  if (isBareLowerV) return true
+
+  const isVersionCommand = positionals.length === 1 && positionals[0] === 'version'
+  if (isVersionCommand) return true
+
+  return false
+}
+
 function findProjectRootFrom(startDir) {
   let current = resolve(startDir)
   while (true) {
@@ -67,6 +94,13 @@ function inferProjectRootFromConfigDir(configDir, startDir) {
 
 async function main() {
   const rawArgs = process.argv.slice(2)
+
+  if (isVersionInvocation(rawArgs)) {
+    const { getPackageVersion } = await import('../lib/version.js')
+    console.log(getPackageVersion())
+    return
+  }
+
   const overrideConfigDir = parseConfigDir(rawArgs)
   const filteredArgs = stripConfigDirArgs(rawArgs)
 

package/lib/backend-package.js

@@ -20,6 +20,11 @@ import { parse as parseYaml } from 'yaml'
 import { logger } from './logger.js'
 import { execManager } from './exec.js'
 import { envManager } from './env.js'
+import {
+  loadEnvPolicy,
+  resolvePolicyTargetId,
+  resolveTargetRequiredVars,
+} from './env-policy.js'
 
 class BackendPackager {
   constructor(options = {}) {
@@ -233,7 +238,19 @@ class BackendPackager {
 
   async prepareEnvSnapshot() {
     logger.info('校验并快照环境变量')
-    const requiredVars = envManager.getRequiredEnvVars(this.layerEnv, 'backend')
+    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 collected = envManager.collectEnvFromLayers('backend', this.layerEnv)
     const effectiveEnv = { ...collected, ...process.env }
     const { valid, missing, placeholders } = envManager.validateRequiredVars(

package/lib/cli/dx-cli.js

@@ -5,6 +5,11 @@ import { logger } from '../logger.js'
 import { envManager } from '../env.js'
 import { execManager } from '../exec.js'
 import { validateEnvironment } from '../validate-env.js'
+import {
+  loadEnvPolicy,
+  resolvePolicyTargetId,
+  resolveTargetRequiredVars,
+} from '../env-policy.js'
 import { FLAG_DEFINITIONS, parseFlags } from './flags.js'
 import { getCleanArgs } from './args.js'
 import { showHelp, showCommandHelp } from './help.js'
@@ -215,7 +220,19 @@ class DxCli {
       // 非 CI 环境下，检查 backend 组的环境变量
       if (process.env.CI !== '1') {
         const effectiveEnv = { ...process.env, ...layeredEnv }
-        const requiredVars = envManager.getRequiredEnvVars(environment, 'backend')
+        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')
+        }
         if (requiredVars.length > 0) {
           const { valid, missing, placeholders } = envManager.validateRequiredVars(
             requiredVars,

package/lib/env-policy.js

@@ -0,0 +1,135 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const DEFAULT_POLICY_PATH = 'env-policy.jsonc'
+
+let cachedPolicy = null
+let cachedPolicyDir = null
+
+function sanitizeJsonc(raw) {
+  return raw.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '')
+}
+
+function assertStringArray(value, fieldPath) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${fieldPath} 必须是数组`)
+  }
+  const invalid = value.filter(v => typeof v !== 'string' || v.trim().length === 0)
+  if (invalid.length > 0) {
+    throw new Error(`${fieldPath} 中存在非法值，请使用非空字符串`)
+  }
+}
+
+function assertRecord(value, fieldPath) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${fieldPath} 必须是对象`)
+  }
+}
+
+export function loadEnvPolicy(configDir) {
+  if (cachedPolicy && cachedPolicyDir === configDir) return cachedPolicy
+
+  const policyPath = join(configDir, DEFAULT_POLICY_PATH)
+  if (!existsSync(policyPath)) {
+    cachedPolicy = null
+    cachedPolicyDir = configDir
+    return null
+  }
+
+  let parsed
+  try {
+    const raw = readFileSync(policyPath, 'utf8')
+    parsed = JSON.parse(sanitizeJsonc(raw) || '{}')
+  } catch (error) {
+    throw new Error(`无法解析 ${DEFAULT_POLICY_PATH}: ${error.message}`)
+  }
+
+  validateEnvPolicy(parsed)
+  cachedPolicy = parsed
+  cachedPolicyDir = configDir
+  return cachedPolicy
+}
+
+export function validateEnvPolicy(policy) {
+  assertRecord(policy, 'env-policy')
+
+  if (policy.version !== 1) {
+    throw new Error('env-policy.jsonc.version 必须为 1')
+  }
+
+  assertStringArray(policy.environments, 'env-policy.jsonc.environments')
+
+  if (typeof policy.secretPlaceholder !== 'string' || policy.secretPlaceholder.trim().length === 0) {
+    throw new Error('env-policy.jsonc.secretPlaceholder 必须为非空字符串')
+  }
+
+  assertRecord(policy.keys, 'env-policy.jsonc.keys')
+  assertStringArray(policy.keys.secret || [], 'env-policy.jsonc.keys.secret')
+  assertStringArray(policy.keys.localOnly || [], 'env-policy.jsonc.keys.localOnly')
+  assertStringArray(policy.keys.localOverride || [], 'env-policy.jsonc.keys.localOverride')
+
+  assertRecord(policy.layout, 'env-policy.jsonc.layout')
+  assertStringArray(policy.layout.forbidExact || [], 'env-policy.jsonc.layout.forbidExact')
+  assertStringArray(policy.layout.allowRoot || [], 'env-policy.jsonc.layout.allowRoot')
+  assertStringArray(policy.layout.allowSubdirGlobs || [], 'env-policy.jsonc.layout.allowSubdirGlobs')
+
+  assertRecord(policy.appToTarget || {}, 'env-policy.jsonc.appToTarget')
+  for (const [app, target] of Object.entries(policy.appToTarget || {})) {
+    if (typeof app !== 'string' || app.trim().length === 0) {
+      throw new Error('env-policy.jsonc.appToTarget 中存在非法 app key')
+    }
+    if (typeof target !== 'string' || target.trim().length === 0) {
+      throw new Error('env-policy.jsonc.appToTarget 中存在非法 target value')
+    }
+  }
+
+  assertRecord(policy.targets, 'env-policy.jsonc.targets')
+  const targetIds = Object.keys(policy.targets)
+  if (targetIds.length === 0) {
+    throw new Error('env-policy.jsonc.targets 不能为空')
+  }
+
+  for (const [targetId, target] of Object.entries(policy.targets)) {
+    if (typeof targetId !== 'string' || targetId.trim().length === 0) {
+      throw new Error('env-policy.jsonc.targets 中存在非法 targetId')
+    }
+    assertRecord(target, `env-policy.jsonc.targets.${targetId}`)
+    assertRecord(target.files, `env-policy.jsonc.targets.${targetId}.files`)
+    if (typeof target.files.committed !== 'string' || target.files.committed.trim().length === 0) {
+      throw new Error(`env-policy.jsonc.targets.${targetId}.files.committed 必须为非空字符串`)
+    }
+    if (typeof target.files.local !== 'string' || target.files.local.trim().length === 0) {
+      throw new Error(`env-policy.jsonc.targets.${targetId}.files.local 必须为非空字符串`)
+    }
+    assertRecord(target.required || {}, `env-policy.jsonc.targets.${targetId}.required`)
+
+    for (const [group, keys] of Object.entries(target.required || {})) {
+      assertStringArray(keys, `env-policy.jsonc.targets.${targetId}.required.${group}`)
+    }
+  }
+
+  // Ensure appToTarget does not point to missing targets.
+  for (const [app, target] of Object.entries(policy.appToTarget || {})) {
+    if (!policy.targets[target]) {
+      throw new Error(
+        `env-policy.jsonc.appToTarget.${app} 指向不存在的 target: ${target}（请在 env-policy.jsonc.targets 中定义）`,
+      )
+    }
+  }
+}
+
+export function resolvePolicyTargetId(policy, app) {
+  if (!policy || !app) return null
+  const mapped = policy.appToTarget?.[app]
+  return mapped || null
+}
+
+export function resolveTargetRequiredVars(policy, targetId, environment) {
+  if (!policy || !targetId) return []
+  const target = policy.targets?.[targetId]
+  if (!target) return []
+  const required = target.required || {}
+  const common = Array.isArray(required._common) ? required._common : []
+  const envSpecific = Array.isArray(required[environment]) ? required[environment] : []
+  return Array.from(new Set([...common, ...envSpecific]))
+}

package/lib/exec.js

@@ -3,6 +3,11 @@ import { promisify } from 'node:util'
 import { logger } from './logger.js'
 import { envManager } from './env.js'
 import { validateEnvironment } from './validate-env.js'
+import {
+  loadEnvPolicy,
+  resolvePolicyTargetId,
+  resolveTargetRequiredVars,
+} from './env-policy.js'
 import { confirmManager } from './confirm.js'
 
 const execPromise = promisify(nodeExec)
@@ -69,17 +74,33 @@ export class ExecManager {
         })
       }
 
-      const effectiveEnv = { ...process.env, ...layeredEnv }
-      // CI 环境跳过后端环境变量校验（CI 中 build backend 只生成 OpenAPI，不需要数据库连接）
-      // 根据 app 参数确定需要检查的环境变量组
-      const isCI = process.env.CI === '1'
-      const appType = isCI ? null : (app === 'backend' ? 'backend' : app ? 'frontend' : null)
-      const requiredVars = envManager.getRequiredEnvVars(environment, appType)
-      if (requiredVars.length > 0) {
-        const { valid, missing, placeholders } = envManager.validateRequiredVars(
-          requiredVars,
-          effectiveEnv,
-        )
+       const effectiveEnv = { ...process.env, ...layeredEnv }
+       const isCI = process.env.CI === '1'
+
+       const policy = loadEnvPolicy(envManager.configDir)
+       let requiredVars = []
+
+       if (!isCI && policy && app) {
+         const targetId = resolvePolicyTargetId(policy, app)
+         if (!targetId) {
+           throw new Error(
+             `未找到 app 对应的 target 配置: app=${app}\n请在 dx/config/env-policy.jsonc 中配置 appToTarget.${app}`,
+           )
+         }
+         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) {
+         const { valid, missing, placeholders } = envManager.validateRequiredVars(
+           requiredVars,
+           effectiveEnv,
+         )
         if (!valid) {
           const problems = ['环境变量校验未通过']
           if (missing.length > 0) {

package/lib/validate-env.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { loadEnvPolicy } from './env-policy.js'
 
 const ROOT_DIR = process.env.DX_PROJECT_ROOT || process.cwd()
 const CONFIG_DIR = process.env.DX_CONFIG_DIR || join(ROOT_DIR, 'dx', 'config')
@@ -41,22 +42,34 @@ export function validateEnvironment() {
     delete process.env.APP_ENV
   }
 
-  enforceRootOnlyEnvFiles()
-  enforceLocalSecretWhitelist()
+  const policy = loadEnvPolicy(CONFIG_DIR)
+
+  enforceRootOnlyEnvFiles(policy)
   enforceGlobalLocalFileProhibited()
-  enforceNonLocalSecretPlaceholders()
-  enforceEnvExampleSecrets()
+
+  if (policy) {
+    enforceSecretPolicy(policy)
+    enforceEnvExamplePolicy(policy)
+  } else {
+    // Backward-compatible behavior
+    enforceLocalSecretWhitelist()
+    enforceNonLocalSecretPlaceholders()
+    enforceEnvExampleSecrets()
+  }
 
   return { nodeEnv: process.env.NODE_ENV, appEnv: process.env.APP_ENV }
 }
 
-function enforceRootOnlyEnvFiles() {
+function enforceRootOnlyEnvFiles(policy) {
   if (existsSync(ROOT_ENV_FILE)) {
     throw new Error(
       '检测到根目录存在 .env 文件，请迁移到 .env.<env> / .env.<env>.local 并删除 .env',
     )
   }
 
+  // 保留现有规则：禁止子目录出现任意 .env* 文件（除特例路径）
+  // 注：该规则对是否启用 env-policy 都有效。
+
   const violations = []
   const queue = ['.']
 
@@ -84,6 +97,11 @@ function enforceRootOnlyEnvFiles() {
 
       if (EXTRA_ENV_ALLOWED_PATHS.has(relativePath)) continue
 
+      if (policy) {
+        const globs = Array.isArray(policy.layout?.allowSubdirGlobs) ? policy.layout.allowSubdirGlobs : []
+        if (isAllowedBySimpleGlob(relativePath, globs)) continue
+      }
+
       violations.push(relativePath)
     }
   }
@@ -133,6 +151,175 @@ function enforceGlobalLocalFileProhibited() {
   }
 }
 
+function enforceSecretPolicy(policy) {
+  const placeholder = String(policy.secretPlaceholder || '').trim()
+  const secretKeys = new Set(policy.keys?.secret || [])
+  const localOnlyKeys = new Set(policy.keys?.localOnly || [])
+  const localOverrideKeys = new Set(policy.keys?.localOverride || [])
+
+  const invalidOverlap = findOverlaps([
+    { name: 'keys.secret', set: secretKeys },
+    { name: 'keys.localOnly', set: localOnlyKeys },
+    { name: 'keys.localOverride', set: localOverrideKeys },
+  ])
+  if (invalidOverlap.length > 0) {
+    throw new Error(`env-policy.jsonc keys 分类存在重复: ${invalidOverlap.join(', ')}`)
+  }
+
+  const errors = []
+  const filePairs = listTargetEnvFilePairs(policy)
+
+  for (const envName of policy.environments || []) {
+    for (const pair of filePairs) {
+      const committed = replaceEnvToken(pair.committed, envName)
+      const local = replaceEnvToken(pair.local, envName)
+
+      const committedPath = join(ROOT_DIR, committed)
+      const localPath = join(ROOT_DIR, local)
+
+      const committedExists = existsSync(committedPath)
+      const localExists = existsSync(localPath)
+
+      if (!committedExists && !localExists) continue
+      if (!committedExists && localExists) {
+        errors.push(`${committed} 缺失（但存在 ${local}），请补充 committed 模板文件`) 
+        continue
+      }
+
+      const committedEntries = committedExists ? parseEnvFile(committedPath) : new Map()
+      const localEntries = localExists ? parseEnvFile(localPath) : new Map()
+
+      // Committed: secret keys must exist and be placeholder.
+      for (const key of secretKeys) {
+        if (!committedEntries.has(key)) {
+          errors.push(`${committed}: 缺少机密键模板 ${key}`)
+          continue
+        }
+        const rawValue = String(committedEntries.get(key) ?? '')
+        if (rawValue.trim() !== placeholder) {
+          errors.push(`${committed}: 机密键 ${key} 必须使用占位符 ${placeholder}`)
+        }
+      }
+
+      // Committed: localOnly must not appear.
+      for (const key of localOnlyKeys) {
+        if (committedEntries.has(key)) {
+          errors.push(`${committed}: localOnly 键 ${key} 不允许出现在非 local 文件中`)
+        }
+      }
+
+      if (localExists) {
+        const allowedInLocal = new Set([...secretKeys, ...localOnlyKeys, ...localOverrideKeys])
+
+        for (const [key, value] of localEntries.entries()) {
+          if (!allowedInLocal.has(key)) {
+            errors.push(`${local}: 包含未声明的键 ${key}（请加入 env-policy.jsonc.keys.* 或迁移到 committed 文件）`)
+            continue
+          }
+
+          if (secretKeys.has(key)) {
+            if (String(value ?? '').trim() === placeholder) {
+              errors.push(`${local}: 机密键 ${key} 不允许使用占位符，请设置真实值`)
+            }
+            if (!committedEntries.has(key)) {
+              errors.push(`${committed}: 缺少机密键模板 ${key}（因为 ${local} 中存在该键）`)
+            }
+          }
+
+          if (localOnlyKeys.has(key) && committedEntries.has(key)) {
+            errors.push(`${committed}: localOnly 键 ${key} 不允许出现在 committed 文件中（已在 ${local} 中存在）`)
+          }
+        }
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`环境变量机密策略校验未通过:\n${errors.join('\n')}`)
+  }
+}
+
+function enforceEnvExamplePolicy(policy) {
+  if (!existsSync(ENV_EXAMPLE_FILE)) return
+
+  const placeholder = String(policy.secretPlaceholder || '').trim()
+  const secretKeys = new Set(policy.keys?.secret || [])
+  const localOnlyKeys = new Set(policy.keys?.localOnly || [])
+  const entries = parseEnvFile(ENV_EXAMPLE_FILE)
+  const errors = []
+
+  for (const [key, value] of entries.entries()) {
+    if (localOnlyKeys.has(key)) {
+      errors.push(`.env.example 不允许包含 localOnly 键: ${key}`)
+      continue
+    }
+    if (secretKeys.has(key)) {
+      if (String(value ?? '').trim() !== placeholder) {
+        errors.push(`.env.example 中机密键 ${key} 必须使用占位符 ${placeholder}`)
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(errors.join('\n'))
+  }
+}
+
+function listTargetEnvFilePairs(policy) {
+  const pairs = []
+  const targets = policy.targets || {}
+  for (const target of Object.values(targets)) {
+    const committed = target?.files?.committed
+    const local = target?.files?.local
+    if (typeof committed !== 'string' || typeof local !== 'string') continue
+    pairs.push({ committed, local })
+  }
+
+  // De-dup
+  const seen = new Set()
+  return pairs.filter(p => {
+    const key = `${p.committed}@@${p.local}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+}
+
+function replaceEnvToken(template, envName) {
+  return String(template).replace(/\{env\}/g, envName)
+}
+
+function isAllowedBySimpleGlob(path, globs) {
+  for (const raw of globs) {
+    const glob = String(raw)
+    if (!glob.includes('*')) {
+      if (glob === path) return true
+      continue
+    }
+    // Only support a single trailing '*' for now.
+    if (glob.endsWith('*')) {
+      const prefix = glob.slice(0, -1)
+      if (path.startsWith(prefix)) return true
+    }
+  }
+  return false
+}
+
+function findOverlaps(namedSets) {
+  const seen = new Map()
+  const overlaps = []
+  for (const { name, set } of namedSets) {
+    for (const key of set) {
+      if (seen.has(key)) {
+        overlaps.push(`${key} (${seen.get(key)} & ${name})`)
+      } else {
+        seen.set(key, name)
+      }
+    }
+  }
+  return overlaps
+}
+
 function enforceNonLocalSecretPlaceholders() {
   const allowlist = loadLocalAllowlist()
   const exemptedKeys = loadExemptedKeys()

package/package.json

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