@ranger1/dx 0.1.82 → 0.1.84

package/lib/backend-artifact-deploy/artifact-builder.js

@@ -8,6 +8,11 @@ import { basenameOrThrow, resolveWithinBase } from './path-utils.js'
 import { createRuntimePackage } from './runtime-package.js'
 
 const execFileAsync = promisify(execFile)
+const tarEnv = {
+  ...process.env,
+  COPYFILE_DISABLE: '1',
+  COPY_EXTENDED_ATTRIBUTES_DISABLE: '1',
+}
 
 function assertSafeNamePart(value, label) {
   const text = String(value || '').trim()
@@ -125,15 +130,21 @@ async function defaultCreateInnerArchive({ stageDir, innerArchivePath }) {
   await mkdir(dirname(innerArchivePath), { recursive: true })
   await execFileAsync('tar', ['-czf', innerArchivePath, '.'], {
     cwd: stageDir,
+    env: tarEnv,
   })
 }
 
 async function defaultWriteChecksum({ archivePath, checksumPath }) {
+  const archiveName = basename(archivePath)
   try {
-    const { stdout } = await execFileAsync('sha256sum', [archivePath])
+    const { stdout } = await execFileAsync('sha256sum', [archiveName], {
+      cwd: dirname(archivePath),
+    })
     await writeFile(checksumPath, stdout)
   } catch {
-    const { stdout } = await execFileAsync('shasum', ['-a', '256', archivePath])
+    const { stdout } = await execFileAsync('shasum', ['-a', '256', archiveName], {
+      cwd: dirname(archivePath),
+    })
     await writeFile(checksumPath, stdout)
   }
 }
@@ -142,7 +153,10 @@ async function defaultCreateBundle({ outputDir, bundlePath, innerArchivePath, ch
   await execFileAsync(
     'tar',
     ['-czf', bundlePath, basename(innerArchivePath), basename(checksumPath)],
-    { cwd: outputDir },
+    {
+      cwd: outputDir,
+      env: tarEnv,
+    },
   )
 }
 

package/lib/backend-artifact-deploy/config.js

@@ -16,6 +16,32 @@ function requirePositiveInteger(value, fieldPath) {
   return parsed
 }
 
+function resolveVerifyConfig(verifyConfig = {}) {
+  const healthCheckConfig = verifyConfig?.healthCheck
+  if (healthCheckConfig == null) {
+    return {
+      healthCheck: null,
+    }
+  }
+
+  const url = requireString(healthCheckConfig.url, 'verify.healthCheck.url')
+  try {
+    new URL(url)
+  } catch {
+    throw new Error(`缺少必填配置: verify.healthCheck.url`)
+  }
+
+  return {
+    healthCheck: {
+      url,
+      timeoutSeconds:
+        healthCheckConfig.timeoutSeconds == null
+          ? 10
+          : requirePositiveInteger(healthCheckConfig.timeoutSeconds, 'verify.healthCheck.timeoutSeconds'),
+    },
+  }
+}
+
 function resolveBuildCommand(buildConfig, environment) {
   if (buildConfig?.commands && typeof buildConfig.commands === 'object') {
     const selected = buildConfig.commands[environment]
@@ -55,6 +81,7 @@ export function resolveBackendDeployConfig({ cli, targetConfig, environment, fla
   const remoteConfig = deployConfig.remote || null
   const startupConfig = deployConfig.startup || {}
   const runConfig = deployConfig.deploy || {}
+  const verifyConfig = deployConfig.verify || {}
   const buildOnly = Boolean(flags.buildOnly)
   const startupMode = String(startupConfig.mode || 'pm2').trim()
   const prismaGenerate = runConfig.prismaGenerate !== false
@@ -117,6 +144,7 @@ export function resolveBackendDeployConfig({ cli, targetConfig, environment, fla
       prismaMigrateDeploy,
       skipMigration: Boolean(flags.skipMigration),
     },
+    verify: resolveVerifyConfig(verifyConfig),
   }
 
   if (!['pm2', 'direct'].includes(normalized.startup.mode)) {

package/lib/backend-artifact-deploy/remote-phases.js

@@ -8,6 +8,7 @@ export function createRemotePhaseModel(payload) {
     { phase: 'prisma-migrate', payload },
     { phase: 'switch-current', payload },
     { phase: 'startup', payload },
+    { phase: 'verify', payload },
     { phase: 'cleanup', payload },
   ]
 }

package/lib/backend-artifact-deploy/remote-script.js

@@ -8,7 +8,11 @@ export function buildRemoteDeployScript(phaseModel = []) {
   const runtime = payload.runtime || {}
   const startup = payload.startup || {}
   const deploy = payload.deploy || {}
+  const verify = payload.verify || {}
+  const healthCheck = verify.healthCheck || null
   const environment = String(payload.environment || 'production')
+  const expectedAppEnv = environment
+  const expectedNodeEnv = environment === 'development' ? 'development' : 'production'
   const baseDir = String(remote.baseDir || '.')
   const releaseDir = `${baseDir}/releases/${payload.versionName || 'unknown'}`
   const currentLink = `${baseDir}/current`
@@ -26,6 +30,8 @@ export function buildRemoteDeployScript(phaseModel = []) {
   const keepReleases = Number(deploy.keepReleases || 5)
   const shouldGenerate = deploy.prismaGenerate !== false
   const shouldMigrate = deploy.prismaMigrateDeploy !== false && deploy.skipMigration !== true
+  const healthCheckUrl = healthCheck?.url ? String(healthCheck.url) : ''
+  const healthCheckTimeoutSeconds = Number(healthCheck?.timeoutSeconds || 10)
 
   return `#!/usr/bin/env bash
 set -euo pipefail
@@ -36,6 +42,8 @@ ARCHIVE=${escapeShell(uploadedBundlePath)}
 RELEASE_DIR=${escapeShell(releaseDir)}
 CURRENT_LINK=${escapeShell(currentLink)}
 ENV_NAME=${escapeShell(environment)}
+EXPECTED_APP_ENV=${escapeShell(expectedAppEnv)}
+EXPECTED_NODE_ENV=${escapeShell(expectedNodeEnv)}
 ENV_FILE_NAME=${escapeShell(envFileName)}
 ENV_LOCAL_FILE_NAME=${escapeShell(envLocalFileName)}
 PRISMA_SCHEMA=${escapeShell(prismaSchema)}
@@ -45,6 +53,8 @@ INSTALL_COMMAND=${escapeShell(installCommand)}
 START_MODE=${escapeShell(startupMode)}
 SERVICE_NAME=${escapeShell(serviceName)}
 START_ENTRY=${escapeShell(startupEntry)}
+HEALTHCHECK_URL=${escapeShell(healthCheckUrl)}
+HEALTHCHECK_TIMEOUT_SECONDS=${healthCheckTimeoutSeconds}
 KEEP_RELEASES=${keepReleases}
 SHOULD_GENERATE=${shouldGenerate ? '1' : '0'}
 SHOULD_MIGRATE=${shouldMigrate ? '1' : '0'}
@@ -157,15 +167,16 @@ find_single_bundle_file() {
 
 sha256_check() {
   local checksum_file="$1"
-  if command -v sha256sum >/dev/null 2>&1; then
-    sha256sum -c "$checksum_file"
-    return
-  fi
-  local checksum expected file
+  local checksum file actual
   checksum="$(awk '{print $1}' "$checksum_file")"
   file="$(awk '{print $2}' "$checksum_file")"
-  expected="$(shasum -a 256 "$file" | awk '{print $1}')"
-  [[ "$checksum" == "$expected" ]]
+  file="$(basename "$file")"
+  if command -v sha256sum >/dev/null 2>&1; then
+    actual="$(sha256sum "$file" | awk '{print $1}')"
+  else
+    actual="$(shasum -a 256 "$file" | awk '{print $1}')"
+  fi
+  [[ "$checksum" == "$actual" ]]
 }
 
 run_with_env() {
@@ -173,10 +184,22 @@ run_with_env() {
   shift
   (
     cd "$cwd"
-    APP_ENV="$ENV_NAME" "$DOTENV_BIN" -o -e "$ENV_FILE_NAME" -e "$ENV_LOCAL_FILE_NAME" -- "$@"
+    APP_ENV="$EXPECTED_APP_ENV" NODE_ENV="$EXPECTED_NODE_ENV" \\
+      "$DOTENV_BIN" -o -e "$ENV_FILE_NAME" -e "$ENV_LOCAL_FILE_NAME" -- "$@"
   )
 }
 
+read_pm2_env_var() {
+  local key="$1"
+  pm2 jlist | node -e '
+    const fs = require("node:fs")
+    const key = process.argv[1]
+    const list = JSON.parse(fs.readFileSync(0, "utf8"))
+    const app = list.find(item => item?.name === process.argv[2])
+    process.stdout.write(String(app?.pm2_env?.[key] || ""))
+  ' "$key" "$SERVICE_NAME"
+}
+
 attempt_pm2_restore() {
   if [[ -z "$PREVIOUS_CURRENT_TARGET" || ! -e "$PREVIOUS_CURRENT_TARGET/$ECOSYSTEM_CONFIG" ]]; then
     ROLLBACK_SUCCEEDED=false
@@ -184,7 +207,8 @@ attempt_pm2_restore() {
   fi
   if (
     cd "$PREVIOUS_CURRENT_TARGET"
-    APP_ENV="$ENV_NAME" "$DOTENV_BIN" -o -e "$ENV_FILE_NAME" -e "$ENV_LOCAL_FILE_NAME" -- \\
+    APP_ENV="$EXPECTED_APP_ENV" NODE_ENV="$EXPECTED_NODE_ENV" \\
+      "$DOTENV_BIN" -o -e "$ENV_FILE_NAME" -e "$ENV_LOCAL_FILE_NAME" -- \\
       pm2 start "$ECOSYSTEM_CONFIG" --only "$SERVICE_NAME" --update-env
     pm2 save
   ); then
@@ -213,7 +237,7 @@ CURRENT_PHASE="extract"
 echo "DX_REMOTE_PHASE=extract"
 validate_archive_entries "$ARCHIVE"
 BUNDLE_TEMP_DIR="$(mktemp -d "$APP_ROOT/.bundle-extract.XXXXXX")"
-tar -xzf "$ARCHIVE" -C "$BUNDLE_TEMP_DIR" --strip-components=1
+tar -xzf "$ARCHIVE" -C "$BUNDLE_TEMP_DIR"
 
 INNER_ARCHIVE="$(find_single_bundle_file "$BUNDLE_TEMP_DIR" 'backend-v*.tgz')"
 INNER_ARCHIVE_SHA256_FILE="$(find_single_bundle_file "$BUNDLE_TEMP_DIR" 'backend-v*.tgz.sha256')"
@@ -290,7 +314,8 @@ if [[ "$START_MODE" == "pm2" ]]; then
   if ! (
     cd "$CURRENT_LINK"
     pm2 delete "$SERVICE_NAME" || true
-    APP_ENV="$ENV_NAME" "$DOTENV_BIN" -o -e "$ENV_FILE_NAME" -e "$ENV_LOCAL_FILE_NAME" -- \\
+    APP_ENV="$EXPECTED_APP_ENV" NODE_ENV="$EXPECTED_NODE_ENV" \\
+      "$DOTENV_BIN" -o -e "$ENV_FILE_NAME" -e "$ENV_LOCAL_FILE_NAME" -- \\
       pm2 start "$ECOSYSTEM_CONFIG" --only "$SERVICE_NAME" --update-env
     pm2 save
   ); then
@@ -305,7 +330,8 @@ if [[ "$START_MODE" == "pm2" ]]; then
 else
   if ! (
     cd "$CURRENT_LINK"
-    APP_ENV="$ENV_NAME" "$DOTENV_BIN" -o -e "$ENV_FILE_NAME" -e "$ENV_LOCAL_FILE_NAME" -- \\
+    APP_ENV="$EXPECTED_APP_ENV" NODE_ENV="$EXPECTED_NODE_ENV" \\
+      "$DOTENV_BIN" -o -e "$ENV_FILE_NAME" -e "$ENV_LOCAL_FILE_NAME" -- \\
       node "$START_ENTRY"
   ); then
     emit_result false "startup" "direct startup failed" false null
@@ -315,6 +341,50 @@ else
   exit 0
 fi
 
+CURRENT_PHASE="verify"
+echo "DX_REMOTE_PHASE=verify"
+if [[ ! -L "$CURRENT_LINK" ]]; then
+  echo "current 软链接不存在: $CURRENT_LINK" >&2
+  exit 1
+fi
+
+current_release="$(readlink -f "$CURRENT_LINK")"
+expected_release="$(readlink -f "$RELEASE_DIR")"
+if [[ -z "$current_release" || ! -d "$current_release" ]]; then
+  echo "current 软链接未指向有效目录: \${current_release:-<empty>}" >&2
+  exit 1
+fi
+if [[ "$current_release" != "$expected_release" ]]; then
+  echo "current 软链接未指向本次 release: expected=$expected_release actual=$current_release" >&2
+  exit 1
+fi
+
+if [[ "$START_MODE" == "pm2" ]]; then
+  if ! pm2 describe "$SERVICE_NAME" >/dev/null 2>&1; then
+    echo "PM2 进程不存在: $SERVICE_NAME" >&2
+    pm2 list || true
+    exit 1
+  fi
+
+  pm2_app_env="$(read_pm2_env_var APP_ENV)"
+  if [[ "$pm2_app_env" != "$EXPECTED_APP_ENV" ]]; then
+    echo "APP_ENV 不匹配，期望=$EXPECTED_APP_ENV，实际=\${pm2_app_env:-<empty>}" >&2
+    pm2 describe "$SERVICE_NAME" || true
+    exit 1
+  fi
+
+  pm2_node_env="$(read_pm2_env_var NODE_ENV)"
+  if [[ "$pm2_node_env" != "$EXPECTED_NODE_ENV" ]]; then
+    echo "NODE_ENV 不匹配，期望=$EXPECTED_NODE_ENV，实际=\${pm2_node_env:-<empty>}" >&2
+    pm2 describe "$SERVICE_NAME" || true
+    exit 1
+  fi
+fi
+
+if [[ -n "$HEALTHCHECK_URL" ]]; then
+  curl -fsS --max-time "$HEALTHCHECK_TIMEOUT_SECONDS" "$HEALTHCHECK_URL" >/dev/null
+fi
+
 CURRENT_PHASE="cleanup"
 echo "DX_REMOTE_PHASE=cleanup"
 release_count=0

package/lib/backend-artifact-deploy/remote-transport.js

@@ -100,6 +100,7 @@ function createRemotePayload(config, bundle) {
     },
     startup: config.startup,
     deploy: config.deploy,
+    verify: config.verify,
   }
 }
 
@@ -114,5 +115,9 @@ export async function deployBackendArtifactRemotely(config, bundle, deps = {}) {
   const phaseModel = createRemotePhaseModel(payload)
   const script = buildRemoteDeployScript(phaseModel)
   const commandResult = await runRemoteScript(config.remote, script)
-  return parseRemoteResult(commandResult)
+  const result = parseRemoteResult(commandResult)
+  if (!result.ok) {
+    throw new Error(`远端部署失败(${result.phase}): ${result.message}`)
+  }
+  return result
 }

package/lib/backend-artifact-deploy/runtime-package.js

@@ -1,5 +1,5 @@
 const UNSUPPORTED_LOCAL_DEP_PATTERN = /^(workspace:|file:|link:)/
-const REQUIRED_DEPENDENCIES_FROM_DEV = ['prisma']
+const REQUIRED_DEPENDENCIES = ['prisma', 'tslib', 'dotenv-cli', '@prisma/adapter-pg']
 
 function assertSupportedDependencies(dependencies = {}) {
   for (const [name, version] of Object.entries(dependencies)) {
@@ -13,10 +13,15 @@ function assertSupportedDependencies(dependencies = {}) {
 export function createRuntimePackage({ appPackage, rootPackage }) {
   const runtimeDependencies = { ...(appPackage?.dependencies || {}) }
   const appDevDependencies = appPackage?.devDependencies || {}
-
-  for (const dependencyName of REQUIRED_DEPENDENCIES_FROM_DEV) {
-    if (!runtimeDependencies[dependencyName] && appDevDependencies[dependencyName]) {
-      runtimeDependencies[dependencyName] = appDevDependencies[dependencyName]
+  const rootDependencies = rootPackage?.dependencies || {}
+  const rootDevDependencies = rootPackage?.devDependencies || {}
+
+  for (const dependencyName of REQUIRED_DEPENDENCIES) {
+    if (!runtimeDependencies[dependencyName]) {
+      runtimeDependencies[dependencyName] =
+        appDevDependencies[dependencyName]
+        || rootDependencies[dependencyName]
+        || rootDevDependencies[dependencyName]
     }
   }
 

package/package.json

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

package/codex/skills/backend-artifact-deploy/SKILL.md

@@ -1,122 +0,0 @@
----
-name: backend-artifact-deploy
-description: 将后端部署从“目标机拉源码并编译”改造为“本地构建制品、目标机仅安装运行依赖并启动”的标准流程。用于 Node/NestJS/Nx/Prisma 等后端项目，尤其适合需要无源码部署、支持 dev/staging/prod 多环境、要求双层环境文件覆盖（如 .env.production 与 .env.production.local）、以及需要在 pm2 与 direct 启动方式之间切换的场景。
----
-
-# 后端制品部署
-
-## 概览
-
-使用该技能时，先识别项目当前的环境变量加载链路与启动链路，再落地“制品打包脚本 + 服务器发布脚本 + 回滚策略”。
-目标是保证目标机器不需要源码编译，同时保持与项目既有环境覆盖规则一致。
-
-## 执行流程
-
-### 第一步：确认现状链路
-
-依次核对：
-
-1. 构建链路是否依赖源码目录（例如 dist 里软链回源码 `node_modules`）。
-2. 运行链路如何加载环境变量（是否是两层覆盖，是否通过 `dotenv -e A -e B`）。
-3. 数据库迁移链路是否依赖运行时环境（Prisma `generate` / `migrate deploy` 前是否已加载 env）。
-4. 进程启动是否仅支持 pm2，是否需要 direct 前台测试模式。
-
-如果项目已有统一入口（例如 `dx` 或内部脚手架），优先复用该入口，不要绕开既有环境策略。
-
-### 第二步：定义制品边界
-
-默认采用“轻制品”模式：
-
-1. 本地只打包编译产物与必要运行文件，不打包 `node_modules`。
-2. 目标机解压后再安装生产依赖。
-3. 制品命名固定含版本与时间片，例如 `backend-v<version>-<月-日-时-分>.tgz`。
-
-制品最小清单应包含：
-
-1. 编译产物目录（如 `dist/backend/**`）。
-2. 数据库 schema 与迁移目录（如 `prisma/schema/**`）。
-3. 生产依赖清单（`package.production.json` 重命名为 `package.json`）。
-4. 锁文件（`pnpm-lock.yaml`）。
-5. 启动配置（如 `ecosystem.config.cjs`）。
-6. 双层环境文件（`.env.<env>` 与 `.env.<env>.local`）。
-
-### 第三步：实现打包脚本
-
-打包脚本应支持参数：
-
-1. `--env dev|staging|prod`。
-2. `--version`（默认取后端 `package.json` 版本）。
-3. `--time`（格式 `MM-DD-HH-mm`）。
-
-脚本关键行为：
-
-1. 按环境构建（`dev -> --dev`，`staging/prod -> --prod`）。
-2. 复制双层环境文件到制品目录。
-3. 不在本地安装运行依赖。
-4. 生成 `tgz`。
-
-### 第四步：实现发布脚本
-
-发布脚本应支持参数：
-
-1. `--archive`（必填）。
-2. `--env dev|staging|prod`。
-3. `--start-mode pm2|direct`（默认 `pm2`）。
-4. `--env-file` 与 `--env-local-file`（可选覆盖路径）。
-5. `--skip-install`、`--skip-migration`、`--skip-pm2`。
-
-发布顺序建议：
-
-1. 解压到 `releases/<version>`。
-2. 准备双层 env 文件。
-3. 安装生产依赖。
-4. 执行 `prisma generate`。
-5. 执行 `prisma migrate deploy`。
-6. 切换 `current` 软链。
-7. 启动服务（pm2 或 direct）。
-8. 清理旧版本。
-
-### 第五步：双层环境加载规则（必须一致）
-
-所有关键步骤统一使用相同加载顺序：
-
-1. 基础层 `.env.<env>`。
-2. 覆盖层 `.env.<env>.local`。
-
-推荐显式写法：
-
-```bash
-APP_ENV="<env-name>" pnpm exec dotenv -e ".env.<env-name>" -e ".env.<env-name>.local" -- <command>
-```
-
-命令示例中的 `<command>` 包括：
-
-1. `pnpm exec prisma generate --schema=...`
-2. `pnpm exec prisma migrate deploy --schema=...`
-3. `pm2 startOrReload ...` 或 `node apps/backend/src/main.js`
-
-## 验证清单
-
-交付前必须至少验证：
-
-1. 打包脚本 `--help` 与语法检查通过。
-2. 发布脚本 `--help` 与语法检查通过。
-3. 制品内同时包含 `.env.<env>` 与 `.env.<env>.local`。
-4. 发布脚本在默认路径下能正确识别并使用两层 env。
-5. `start-mode=direct` 可前台启动。
-6. `start-mode=pm2` 可重载或启动。
-7. 版本目录与 `current` 切换正常，可回滚。
-
-## 常见陷阱
-
-1. 把 env 文件链接到自身，造成坏链路。
-2. 只加载 `.env.<env>`，遗漏 `.local` 覆盖。
-3. 迁移与启动阶段用不同 env 加载逻辑，导致行为不一致。
-4. staging 构建误用 development 或 production 的 env 层。
-5. 打包包含本机 `node_modules`，跨系统运行失败。
-
-## 参考资料
-
-需要细化实现时，读取：
-
-- `references/deployment-checklist.md`

package/codex/skills/backend-artifact-deploy/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "后端制品部署"
-  short_description: "跨项目复用的后端制品构建发布与双层环境变量合并流程"
-  default_prompt: "Use $backend-artifact-deploy to design and implement source-free backend artifact deployment with layered env handling."

package/codex/skills/backend-artifact-deploy/references/deployment-checklist.md

@@ -1,66 +0,0 @@
-# 后端制品部署检查清单
-
-## 一、改造前采样
-
-1. 查找构建后是否存在软链回源码依赖：
-
-```bash
-rg -n "ln -sfn.*node_modules|node_modules.*ln -sfn" <backend-package-json-path>
-```
-
-2. 查找环境加载入口：
-
-```bash
-rg -n "dotenv -e|dotenv --override|ConfigModule.forRoot|loadEnvironment|env-layers" -S <repo-root>
-```
-
-3. 查找启动命令：
-
-```bash
-rg -n "start:prod|pm2|node .*main" -S <repo-root>
-```
-
-## 二、打包脚本最低要求
-
-1. 接收 `--env`、`--version`、`--time`。
-2. 制品名包含版本与时间片。
-3. 打入 `.env.<env>` 与 `.env.<env>.local`。
-4. 不打入 `node_modules`（轻制品模式）。
-
-## 三、发布脚本最低要求
-
-1. 解压到 `releases/<version>` 并切换 `current`。
-2. 支持 `pm2` 与 `direct` 两种启动方式。
-3. 在 install、migrate、start 三阶段都用同一套双层 env 加载顺序。
-4. 支持 `--env-file` 与 `--env-local-file` 覆盖路径。
-
-## 四、上线前验证命令
-
-```bash
-bash -n scripts/release/backend-build-release.sh
-bash -n scripts/release/backend-deploy-release.sh
-scripts/release/backend-build-release.sh --env staging
-tar -tzf release/backend/*.tgz | rg "\.env\.staging(\.local)?$"
-```
-
-## 五、发布后验证
-
-1. 进程检查：
-
-```bash
-pm2 status
-pm2 logs backend --lines 120
-```
-
-2. 健康检查：
-
-```bash
-curl -f http://127.0.0.1:3000/health
-```
-
-3. 回滚检查：
-
-```bash
-ln -sfn /opt/ai-backend/releases/<old-version> /opt/ai-backend/current
-pm2 reload backend --update-env
-```