@ranger1/dx 0.1.81 → 0.1.83

package/README.md

@@ -362,6 +362,49 @@ dx deploy backend --prod --skip-migration
 
 - 生成的 release `package.json` 默认只保留运行时依赖；如果应用把 `prisma` 放在 `devDependencies`，dx 会自动把它提升进 release 依赖，保证远端 `prisma generate` / `prisma migrate deploy` 可执行。
 - 打包前会递归扫描整个 staged payload；任意层级出现 `.env*` 文件都会直接失败，避免把环境文件误打进制品。
+- 所有本地路径字段都会被解析为相对项目根目录，并且必须留在项目根目录内；例如 `build.distDir`、`runtime.prismaSchemaDir`、`artifact.outputDir` 不能通过 `../` 逃逸到仓库外。
+- `remote.baseDir` 必须是绝对路径，并且只能包含 `/`、字母、数字、`.`、`_`、`-`；不要使用空格或 shell 特殊字符。
+
+SSH 认证说明：
+
+- `dx deploy backend` 当前直接调用系统 `ssh` / `scp`，不会单独解析 `sshKey`、`identityFile` 之类的 dx 配置项。
+- 因此，发布使用哪把私钥，取决于本机 OpenSSH 的默认认证行为，例如 `ssh-agent`、`~/.ssh/config`、默认私钥文件等。
+- 如果你已经在 `~/.ssh/config` 中配置了主机别名（例如 `Host ai-staging`），推荐直接把 `backendDeploy.remote.host` 写成这个别名，让 OpenSSH 自动匹配对应的 `HostName`、`User`、`Port`、`IdentityFile`。
+
+例如本机 `~/.ssh/config`：
+
+```sshconfig
+Host ai-staging
+  HostName 1.2.3.4
+  User deploy
+  Port 22
+  IdentityFile ~/.ssh/your_staging_key
+```
+
+对应的 `dx/config/commands.json`：
+
+```json
+{
+  "deploy": {
+    "backend": {
+      "internal": "backend-artifact-deploy",
+      "backendDeploy": {
+        "remote": {
+          "host": "ai-staging",
+          "port": 22,
+          "user": "deploy",
+          "baseDir": "/srv/example-app"
+        }
+      }
+    }
+  }
+}
+```
+
+注意：
+
+- `remote.host` 写成别名后，dx 仍会显式传入 `remote.user` 和 `remote.port`；如果这两个值与 `~/.ssh/config` 中的 `User` / `Port` 不一致，命令行参数会覆盖 SSH config。
+- 最稳妥的做法是让 `remote.user`、`remote.port` 与 `~/.ssh/config` 保持一致，或者都统一以 SSH config 中的值为准后再同步到 dx 配置。
 
 ## 依赖关系约定
 

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()
@@ -32,12 +37,25 @@ async function defaultReadVersion(versionFile) {
   return String(pkg.version || '').trim()
 }
 
-async function defaultRunBuild(build) {
+export function buildFlagsForEnvironment(environment) {
+  switch (environment || 'development') {
+    case 'production':
+      return { prod: true }
+    case 'staging':
+      return { staging: true }
+    case 'development':
+    default:
+      return { dev: true }
+  }
+}
+
+async function defaultRunBuild(build, environment = 'development') {
   if (!build?.command) {
     throw new Error('缺少构建命令: build.command')
   }
   await execManager.executeCommand(build.command, {
     app: build.app || undefined,
+    flags: buildFlagsForEnvironment(environment),
   })
 }
 
@@ -112,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)
   }
 }
@@ -129,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,
+    },
   )
 }
 
@@ -217,7 +244,7 @@ export async function buildBackendArtifact(config, deps = {}) {
   const checksumPath = resolveWithinBase(outputDir, names.checksumName, 'checksumPath')
   const bundlePath = resolveWithinBase(outputDir, names.bundleName, 'bundlePath')
 
-  await runBuild(config.build)
+  await runBuild(config.build, config.environment)
   await prepareOutputDir(outputDir)
   await stageFiles({
     config,

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

@@ -157,15 +157,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() {
@@ -213,7 +214,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')"

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

@@ -114,5 +114,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.81",
+  "version": "0.1.83",
   "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
-```