@ranger1/dx 0.1.84 → 0.1.86

package/codex/skills/env-accessor-audit-fixer/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: env-accessor-audit-fixer
+description: Use when backend、NestJS、配置模块、E2E 测试或脚本中需要审计或修复 `process.env` 直读，判断项目是否已具备统一环境访问基础设施，并在缺少 EnvAccessor、EnvService、EnvModule 或统一配置接入时补齐最小可用实现。
+---
+
+# 环境变量访问审计与修复
+
+## 概览
+
+先扫描 `process.env` 直读点，再判断仓库是否已有统一 env 访问基础设施。
+
+- 若已有 `EnvService`、`createEnvAccessor`、`defaultEnvAccessor` 或等价封装，优先复用现有方案并逐项迁移。
+- 若缺少统一入口，先补齐最小基础设施，再收口剩余直读点。
+
+## 快速开始
+
+先运行扫描脚本：
+
+```bash
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+python "$CODEX_HOME/skills/env-accessor-audit-fixer/scripts/env_accessor_audit.py" \
+  --workspace /Users/a1/work/ai-monorepo
+```
+
+需要结构化结果时输出 JSON：
+
+```bash
+python "$CODEX_HOME/skills/env-accessor-audit-fixer/scripts/env_accessor_audit.py" \
+  --workspace /Users/a1/work/ai-monorepo \
+  --output-json /tmp/env-accessor-audit.json
+```
+
+若脚本显示尚未形成统一 env 入口，再读取 [references/bootstrap-env-foundation.md](./references/bootstrap-env-foundation.md)。
+
+## 执行流程
+
+1. 扫描 `apps/backend/src` 与 `apps/backend/e2e` 中的 `process.env`。
+2. 仅排除真正的基础封装文件：
+   - `env.accessor.ts`
+   - `env.service.ts`
+3. 不排除 `apps/backend/src/config/**/*.ts`，确保 `registerAs` 配置层也纳入审计。
+4. 优先识别当前基础设施状态：
+   - 是否存在 `createEnvAccessor`
+   - 是否存在 `defaultEnvAccessor`
+   - 是否存在 `EnvService`
+   - 是否存在 `EnvModule`
+   - 是否已有 `registerAs` 或配置层通过统一 env 入口读取变量
+5. 按场景为每个直读点选择迁移方式，而不是机械替换。
+6. 修复后重新扫描，并补跑最小验证，确认配置读取与运行行为一致。
+
+## 快速复核命令
+
+项目具备 `rg` 时，优先用下列命令复核：
+
+```bash
+rg "process\\.env" apps/backend/src apps/backend/e2e \
+  --glob '!*env.accessor.ts' \
+  --glob '!*env.service.ts'
+```
+
+## 修复准则
+
+### 配置层与 `registerAs`
+
+- 优先使用 `defaultEnvAccessor`
+- 仅在必须显式传入环境对象时使用 `createEnvAccessor(process.env)`
+- 不要继续裸读 `process.env.FOO`
+
+```typescript
+import { registerAs } from '@nestjs/config'
+import { defaultEnvAccessor } from '@/common/env/env.accessor'
+
+const env = defaultEnvAccessor
+
+export const redisConfig = registerAs('redis', () => ({
+  host: env.str('REDIS_HOST', 'localhost'),
+}))
+```
+
+### 运行期服务、控制器、提供者
+
+- 注入 `EnvService`
+- 优先使用 `getString`、`getInt`、`getBoolean`、`isProd`、`isE2E` 等 typed getter
+- 若模块尚未暴露 `EnvModule`，先补模块依赖，再迁移读取逻辑
+
+```typescript
+@Injectable()
+export class ExampleService {
+  constructor(private readonly env: EnvService) {}
+
+  getRedisHost() {
+    return this.env.getString('REDIS_HOST', 'localhost')
+  }
+}
+```
+
+### 独立脚本与 CLI
+
+- 在完成 dotenv 装载后显式创建 accessor
+
+```typescript
+const env = createEnvAccessor(process.env)
+```
+
+### 必须读取原始值
+
+- 使用 `EnvService.getAccessor().raw(key)`，或 accessor 的 `raw(key)`
+- 在代码中简短说明为何 typed getter 不适用
+
+## 缺失基础设施时的补齐顺序
+
+若扫描结果显示项目尚未形成统一 env 访问方案，按以下顺序补齐：
+
+1. 创建 `env.accessor.ts`
+   - 提供 `createEnvAccessor`
+   - 提供 `defaultEnvAccessor`
+   - 至少支持 `str`、`bool`、`int`、`num`、`raw`、`appEnv`、`snapshot`
+2. 创建 `env.service.ts`
+   - 包装 `ConfigService`
+   - 提供 typed getter 与常用环境判断方法
+3. 创建 `env.module.ts`
+   - 暴露 `EnvService`
+4. 将配置层迁移到 `registerAs + defaultEnvAccessor`
+5. 将运行期服务迁移到 `EnvService`
+6. 重新扫描剩余 `process.env` 直读点
+
+优先复用现有命名、目录与模块结构；若无统一基础设施，再参考 [references/bootstrap-env-foundation.md](./references/bootstrap-env-foundation.md)。
+
+## 例外与判断原则
+
+- `env.accessor.ts`、`env.service.ts` 本身允许访问 `process.env`
+- 负责 dotenv 装载、环境注入、测试环境临时覆写的底层入口可保留少量受控访问
+- 测试里对 `process.env` 的显式设值可视为受控例外，但优先复用公共 fixture 或 helper
+- 若某文件同时负责“装载环境”和“消费环境”，优先拆分职责，避免例外扩大
+
+## 输出要求
+
+最终输出至少包含：
+
+1. 基础设施状态
+2. `process.env` 直读文件清单
+3. 每个问题的推荐迁移方式
+4. 是否需要补齐基础设施
+5. 已修改内容、验证结果与剩余风险
+
+## 资源
+
+- 扫描脚本：`scripts/env_accessor_audit.py`
+- 补齐模板：`references/bootstrap-env-foundation.md`

package/codex/skills/env-accessor-audit-fixer/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "环境变量审计修复"
+  short_description: "审计并修复 process.env 直读，必要时补齐统一 env 访问基础设施"
+  default_prompt: "使用 $env-accessor-audit-fixer 扫描项目中的 process.env 直读，判断是否已具备统一 env 访问基础设施，并给出或实施修复方案。"
+
+policy:
+  allow_implicit_invocation: true

package/codex/skills/env-accessor-audit-fixer/references/bootstrap-env-foundation.md

@@ -0,0 +1,156 @@
+# 缺失统一 env 基础设施时的最小补齐模板
+
+当扫描结果显示项目尚未具备 `createEnvAccessor`、`defaultEnvAccessor`、`EnvService` 等统一入口时，可按下面的最小骨架补齐。优先复用项目现有工具链、路径别名与公共类型；只有在仓库确实没有对应能力时，才照此新建。
+
+## 1. `env.accessor.ts`
+
+目标：
+
+- 为配置层、脚本、工具函数提供无依赖的统一读取入口
+- 允许显式传入 `process.env` 或自定义 env record
+- 提供 typed getter 与 `raw()` 回退口
+
+最小示例：
+
+```typescript
+export interface EnvAccessor {
+  str(key: string, defaultValue?: string): string | undefined
+  bool(key: string, defaultValue?: boolean): boolean
+  int(key: string, defaultValue?: number): number
+  raw(key: string): string | undefined
+}
+
+type EnvSource = Record<string, string | undefined> | NodeJS.ProcessEnv | undefined
+
+function resolveEnv(source?: EnvSource): Record<string, string | undefined> {
+  return source ? { ...source } : process.env
+}
+
+export function createEnvAccessor(source?: EnvSource): EnvAccessor {
+  const env = resolveEnv(source)
+  return {
+    str(key, defaultValue) {
+      const value = env[key]
+      return value === undefined || value === '' ? defaultValue : value
+    },
+    bool(key, defaultValue = false) {
+      const value = String(env[key] ?? '').toLowerCase()
+      if (!value) return defaultValue
+      return value === 'true' || value === '1'
+    },
+    int(key, defaultValue = 0) {
+      const value = Number.parseInt(String(env[key] ?? ''), 10)
+      return Number.isFinite(value) ? value : defaultValue
+    },
+    raw(key) {
+      return env[key]
+    },
+  }
+}
+
+export const defaultEnvAccessor = createEnvAccessor()
+```
+
+## 2. `env.service.ts`
+
+目标：
+
+- 为 NestJS 运行期服务提供注入式访问方式
+- 统一接入 `ConfigService`
+- 预留缓存、阈值裁剪、调试开关等运行期逻辑
+
+最小示例：
+
+```typescript
+@Injectable()
+export class EnvService {
+  constructor(private readonly config: ConfigService) {}
+
+  getString(key: string, defaultValue?: string): string | undefined {
+    const value = this.config.get<string>(key)
+    return value === undefined || value === null || value === '' ? defaultValue : String(value)
+  }
+
+  getBoolean(key: string, defaultValue = false): boolean {
+    const value = String(this.config.get<string>(key) ?? '').toLowerCase()
+    if (!value) return defaultValue
+    return value === 'true' || value === '1'
+  }
+
+  getInt(key: string, defaultValue = 0): number {
+    const value = Number.parseInt(String(this.config.get<string>(key) ?? ''), 10)
+    return Number.isFinite(value) ? value : defaultValue
+  }
+
+  isProd(): boolean {
+    return this.getString('APP_ENV', this.getString('NODE_ENV', 'development')) === 'production'
+  }
+
+  getAccessor() {
+    return createEnvAccessor(process.env)
+  }
+}
+```
+
+## 3. `env.module.ts`
+
+目标：
+
+- 统一导出 `EnvService`
+- 供业务模块直接导入
+
+最小示例：
+
+```typescript
+@Module({
+  providers: [EnvService],
+  exports: [EnvService],
+})
+export class EnvModule {}
+```
+
+## 4. 配置层接入
+
+配置文件中不要继续写 `process.env.REDIS_HOST`，改为：
+
+```typescript
+import { registerAs } from '@nestjs/config'
+import { defaultEnvAccessor } from '@/common/env/env.accessor'
+
+const env = defaultEnvAccessor
+
+export const redisConfig = registerAs('redis', () => ({
+  host: env.str('REDIS_HOST', 'localhost'),
+  port: env.int('REDIS_PORT', 6379),
+}))
+```
+
+## 5. 运行期服务接入
+
+业务代码中不要继续裸读环境变量，改为：
+
+```typescript
+@Injectable()
+export class ExampleService {
+  constructor(private readonly env: EnvService) {}
+
+  shouldEnableFeature(): boolean {
+    return this.env.getBoolean('FEATURE_FLAG_ENABLED', false)
+  }
+}
+```
+
+## 6. 迁移顺序建议
+
+1. 先落 `env.accessor.ts`
+2. 再落 `env.service.ts` 与 `env.module.ts`
+3. 先迁配置层，再迁服务层
+4. 最后清理残留 `process.env` 直读
+
+## 7. 允许保留的少量例外
+
+- 负责加载 `.env` 文件的底层入口
+- 用于测试注入的 setup / fixture
+- 必须读取原始未加工字符串的极少数路径
+
+即便属于例外，也优先把“装载环境”和“消费环境”拆开，避免把业务逻辑继续锁在 `process.env` 上。

package/codex/skills/env-accessor-audit-fixer/scripts/env_accessor_audit.py

@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_SCAN_DIRS = ["apps/backend/src", "apps/backend/e2e"]
+EXCLUDED_GLOBS = ["!*env.accessor.ts", "!*env.service.ts"]
+
+
+def run_rg(args: list[str], cwd: Path) -> str:
+    result = subprocess.run(
+        ["rg", *args],
+        cwd=str(cwd),
+        text=True,
+        capture_output=True,
+    )
+    if result.returncode not in (0, 1):
+        raise RuntimeError(result.stderr.strip() or "rg failed")
+    return result.stdout
+
+
+def rg_has_matches(pattern: str, paths: list[str], cwd: Path) -> bool:
+    output = run_rg(["-l", pattern, *paths], cwd)
+    return bool(output.strip())
+
+
+def detect_foundation(workspace: Path) -> dict[str, Any]:
+    search_paths = ["apps/backend/src", "apps/backend/e2e"]
+    file_hits = {
+        "env_accessor_file": run_rg(["-l", r"export function createEnvAccessor", *search_paths], workspace)
+        .strip()
+        .splitlines(),
+        "default_accessor_usage": run_rg(["-l", r"defaultEnvAccessor", *search_paths], workspace)
+        .strip()
+        .splitlines(),
+        "env_service_file": run_rg(["-l", r"export class EnvService", *search_paths], workspace)
+        .strip()
+        .splitlines(),
+        "env_service_usage": run_rg(["-l", r"\bEnvService\b", *search_paths], workspace)
+        .strip()
+        .splitlines(),
+        "config_registeras_usage": run_rg(["-l", r"registerAs\(", "apps/backend/src"], workspace)
+        .strip()
+        .splitlines(),
+    }
+    file_hits = {key: [line for line in value if line] for key, value in file_hits.items()}
+
+    foundation = {
+        "has_create_env_accessor": bool(file_hits["env_accessor_file"]),
+        "has_default_env_accessor": bool(file_hits["default_accessor_usage"]),
+        "has_env_service": bool(file_hits["env_service_file"]),
+        "has_register_as_config": bool(file_hits["config_registeras_usage"]),
+        "recommended_mode": "reuse-existing-foundation"
+        if (
+            bool(file_hits["env_accessor_file"])
+            or bool(file_hits["default_accessor_usage"])
+            or bool(file_hits["env_service_file"])
+        )
+        else "bootstrap-foundation",
+        "evidence": file_hits,
+    }
+    return foundation
+
+
+def collect_process_env_findings(workspace: Path, scan_dirs: list[str]) -> list[dict[str, Any]]:
+    args = ["-n", "--column", "process\\.env", *scan_dirs]
+    for glob in EXCLUDED_GLOBS:
+        args.extend(["--glob", glob])
+    output = run_rg(args, workspace)
+
+    findings: list[dict[str, Any]] = []
+    for line in output.strip().splitlines():
+        if not line:
+            continue
+        parts = line.split(":", 3)
+        if len(parts) != 4:
+            continue
+        file_path, line_no, column_no, snippet = parts
+        if is_allowed_process_env_usage(file_path, snippet):
+            continue
+        findings.append(
+            {
+                "file": file_path,
+                "line": int(line_no),
+                "column": int(column_no),
+                "snippet": snippet.strip(),
+                "kind": classify_finding(file_path),
+                "recommended_fix": recommend_fix(file_path),
+            }
+        )
+    return findings
+
+
+def is_allowed_process_env_usage(file_path: str, snippet: str) -> bool:
+    normalized = snippet.replace(" ", "")
+    if file_path.endswith("test-env.helper.ts"):
+        return True
+    if file_path.endswith("load-environment.ts"):
+        return True
+    if file_path.endswith("export-openapi.ts"):
+        return True
+    if file_path.endswith("setup-e2e.ts"):
+        return True
+    if file_path.endswith("fixtures.ts"):
+        return True
+    if file_path.endswith("stream-session.guard.e2e-spec.ts") and "{process.env." in snippet:
+        return True
+    if "createEnvAccessor(process.env)" in normalized:
+        return True
+    if "defaultEnvAccessor=createEnvAccessor(process.env)" in normalized:
+        return True
+    return False
+
+
+def classify_finding(file_path: str) -> str:
+    if "/e2e/" in file_path or file_path.endswith(".spec.ts"):
+        return "test-or-e2e"
+    if "/config/" in file_path or file_path.endswith(".config.ts"):
+        return "config"
+    if file_path.endswith(".ts"):
+        return "runtime"
+    return "unknown"
+
+
+def recommend_fix(file_path: str) -> str:
+    kind = classify_finding(file_path)
+    if kind == "config":
+        return "使用 defaultEnvAccessor 或 createEnvAccessor(process.env)"
+    if kind == "runtime":
+        return "注入 EnvService 并改用 getString/getInt/getBoolean/isProd 等方法"
+    if kind == "test-or-e2e":
+        return "优先收敛到公共 fixture/helper；若属于测试注入，可保留为受控例外并说明原因"
+    return "根据上下文改为 EnvService 或 EnvAccessor"
+
+
+def summarize_findings(findings: list[dict[str, Any]]) -> dict[str, Any]:
+    by_kind: dict[str, int] = {}
+    by_file: dict[str, int] = {}
+    for item in findings:
+        by_kind[item["kind"]] = by_kind.get(item["kind"], 0) + 1
+        by_file[item["file"]] = by_file.get(item["file"], 0) + 1
+    return {
+        "total_findings": len(findings),
+        "by_kind": by_kind,
+        "files": sorted(
+            [{"file": file_path, "count": count} for file_path, count in by_file.items()],
+            key=lambda item: (-item["count"], item["file"]),
+        ),
+    }
+
+
+def build_report(workspace: Path, scan_dirs: list[str]) -> dict[str, Any]:
+    foundation = detect_foundation(workspace)
+    findings = collect_process_env_findings(workspace, scan_dirs)
+    return {
+        "workspace": str(workspace),
+        "scan_dirs": scan_dirs,
+        "excluded_globs": EXCLUDED_GLOBS,
+        "foundation": foundation,
+        "summary": summarize_findings(findings),
+        "findings": findings,
+    }
+
+
+def print_text_report(report: dict[str, Any]) -> None:
+    foundation = report["foundation"]
+    summary = report["summary"]
+
+    print("== env-accessor-audit-fixer ==")
+    print(f"workspace: {report['workspace']}")
+    print(f"scan dirs: {', '.join(report['scan_dirs'])}")
+    print(f"recommended mode: {foundation['recommended_mode']}")
+    print("")
+    print("foundation:")
+    print(f"- has createEnvAccessor: {foundation['has_create_env_accessor']}")
+    print(f"- has defaultEnvAccessor: {foundation['has_default_env_accessor']}")
+    print(f"- has EnvService: {foundation['has_env_service']}")
+    print(f"- has registerAs config: {foundation['has_register_as_config']}")
+    print("")
+    print("summary:")
+    print(f"- total findings: {summary['total_findings']}")
+    for kind, count in sorted(summary["by_kind"].items()):
+        print(f"- {kind}: {count}")
+
+    if not report["findings"]:
+        return
+
+    print("")
+    print("findings:")
+    for item in report["findings"]:
+        print(
+            f"- {item['file']}:{item['line']}:{item['column']} "
+            f"[{item['kind']}] {item['recommended_fix']}"
+        )
+        print(f"  {item['snippet']}")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="审计项目中的 process.env 直读，并判断是否缺少统一 env 访问基础设施。"
+    )
+    parser.add_argument(
+        "--workspace",
+        default=".",
+        help="仓库根目录，默认当前目录",
+    )
+    parser.add_argument(
+        "--scan-dir",
+        dest="scan_dirs",
+        action="append",
+        help="附加扫描目录；默认扫描 apps/backend/src 与 apps/backend/e2e",
+    )
+    parser.add_argument(
+        "--output-json",
+        help="将结构化结果输出到指定文件",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    workspace = Path(args.workspace).resolve()
+    scan_dirs = args.scan_dirs or DEFAULT_SCAN_DIRS
+
+    try:
+        report = build_report(workspace, scan_dirs)
+    except FileNotFoundError:
+        print("未找到 rg，请先安装 ripgrep", file=sys.stderr)
+        return 2
+    except RuntimeError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
+    print_text_report(report)
+
+    if args.output_json:
+        output_path = Path(args.output_json)
+        output_path.write_text(json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())