@weotro/dx 0.2.2 → 0.3.0

package/skills/dx-adopt/references/switch-to-0.3.md

@@ -0,0 +1,61 @@
+# DX 0.3.0 接入与切换向导
+
+本向导及[完整契约](dx-0.3-contract.md)、[经验与回归检查](adoption-regressions.md)一起分发。直接完成 0.3.0 的应用入口和调用方式，不需要访问 dx 源码或经过中间版本。
+
+## 1. 安装并取得说明
+
+沿用应用的全局或项目依赖安装方式。已发布的全局版本可通过以下命令安装并同步资料：
+
+```sh
+npm install -g @weotro/dx@0.3.0
+dx --version
+dx initial
+```
+
+项目依赖由原包管理器安装 `@weotro/dx@0.3.0`，使用该依赖的 CLI 执行同样的版本核验与 initial。待发布验证使用实际提供的 0.3.0 `.tgz`；安装源、开发调用及 CI 应一致。
+
+同步后的阅读入口为 `~/.agents/skills/dx-adopt/SKILL.md`，本目录 references 中包含全部规则和经验。包内另有 README.md、example/README.md 和可运行 example；全局包位于 `npm root -g` 输出下的 `@weotro/dx`，本地包位于项目 `node_modules/@weotro/dx`。这些是安装包路径，无需源码仓库。
+
+完成条件：确认实际 CLI 为 0.3.0，并能在已安装技能目录读取本向导及两个配套参考。
+
+## 2. 将实际功能接到标准入口
+
+盘点当前 package scripts、工具任务、CI、容器及部署调用，建立“功能 → 调用方 → 新入口/目标 → 验证结果”的对应关系。保留真实实现、工具链及确认条件。
+
+在工程根建立七个带有效 shebang、可读可执行的 `dx/scripts/` 入口，以及 `dx/contract.json`。按[契约 JSON 示例](dx-0.3-contract.md#契约声明)声明 `schemaVersion: 1`、目标及每个调用组合的能力状态；辅助实现放在公开入口目录外。
+
+- setup 无位置参数；start/build/lint/deploy 各接一个目标。
+- test 接 unit/e2e 类型与目标；db 接 migrate/seed/reset/status 动作与单目标。
+- start 显式声明 stack；build/lint/deploy 和两种测试各显式声明 all；db 各动作至少一个目标。
+- 每个 unit 目标必须真实实现；确实不适用的其他能力可声明 mock，附原因，由应用输出命令和原因并返回 0。需要但未完成的功能如实保留为未完成项。
+
+完成条件：七个入口、声明与实际功能对应完整，`dx check` 返回 0。静态合规不代表真实功能已验证。
+
+## 3. 一次切换所有调用方
+
+根据实际职责填写目标，不盲目用 all 替代单目标。统一调用形式例如：
+
+```sh
+dx setup
+dx start stack
+dx build all --prod
+dx lint all -- --fix
+dx test unit all
+dx test e2e all
+dx db migrate main --e2e
+dx deploy all --staging
+```
+
+工具专属参数放在首个 `--` 后，由应用按参数数组转交。test 命令固定选择 test/e2e，不接受额外环境标志；其他应用命令默认 dev，最多接受一个环境标志。应用读取 dx 注入的 APP_ENV/NODE_ENV，命令是环境选择来源。
+
+同步 package scripts、CI、容器、部署平台、Playwright webServer、测试内启动命令和开发/agent 指令。E2E 内启动非测试命令也要显式选择环境，如 `dx start stack --e2e`；仅设置父进程 APP_ENV 不会选中 E2E 配置。
+
+完成条件：所有活动调用方使用相同的 0.3.0 来源及语法，搜索替换前的路径和命令后没有遗漏消费者；确认无人使用的包装和配置才清理。
+
+## 4. 用实际行为验收
+
+先 `dx check`，再按需执行 setup 和真实 unit、lint、构建与其他相关功能。标准帮助不会执行业务；扩展帮助和 `-- --help` 仍是应用调用。数据库与部署按项目既有授权使用隔离资源验证。
+
+按[经验与回归检查](adoption-regressions.md)选择涉及的分支，核对实际环境层、最终工具 argv、构建产物、worktree 配置和进程回收。mock 逐项验证日志及退出码。项目本地接入说明链接到已安装的 dx-adopt 资料，写清目标和环境用法。
+
+完成条件：分别记录静态合规、真实通过、mock 跳过和未验证项；implemented 声明与脚本返回 0 均不能替代真实运行证据。

package/skills/dx-adopt/references/dx-0.2-contract.md

@@ -1,95 +0,0 @@
-# DX 0.2.1 能力与调用契约
-
-本文随技能发布，供应用接入时独立使用。实际安装包不同于 0.2.1 时核对行为，不将此表外推为其他版本的保证。
-
-## 能力分界
-
-| dx 提供 | 应用提供 |
-| --- | --- |
-| 最近工程发现、脚本检查、进程调用、退出状态 | 构建、测试、数据库和部署的具体实现 |
-| dotenv 两层加载、dotenv-expand 变量展开、环境选择 | 必需变量与占位符校验、额外服务配置 |
-| setup 前的 worktree 本地文件准备 | 安装依赖、生成文件、准备服务 |
-| initial 的包内技能分发 | 目标项目的代码与脚本；initial 不执行接入迁移 |
-| 帮助与版本查询 | 应用子命令帮助、目标选择、编排和恢复 |
-
-不内置 Nx、Prisma、PM2、Vercel、SDK 构建、制品部署、回滚、端口清理、自动重试或环境策略配置。这些工具可以继续在应用中使用。
-
-## 安装与技能
-
-- 包名 `@weotro/dx`，Node.js 至少 20.11.0；支持 macOS/Linux，不支持 Windows。setup 的 Git 定位需要已安装 Git。
-- 全局安装可独立于应用 node_modules 工作；本地依赖需先有安装它的引导途径。运行时依赖由 dx 包自己携带，应用不必为了 dx 的环境注入安装 dotenv CLI。
-- `dx initial` 使用安装包中的 skills/，覆盖更新 `~/.agents/skills` 的托管技能，为 `~/.claude/skills` 建立链接，并按原规则清理托管旧副本和历史已删除技能。其他技能保留。
-- initial 无需应用工程，不加载项目环境，不运行 setup；setup 也不会自动执行 initial。新技能随包安装后，通过 initial 同步；仅把 dx 版本写入 package.json 不等于技能已更新。
-
-## 脚本路由
-
-```text
-项目根/
-  dx/scripts/setup
-  dx/scripts/start
-  dx/scripts/build
-  dx/scripts/test
-  dx/scripts/db
-  dx/scripts/deploy
-```
-
-按需提供入口，不要求六个全部存在。自定义名称匹配 `[a-z][a-z0-9-]*`；initial 为保留命令。每个入口为可读、可执行、无扩展名的文件，shebang 解释器使用绝对路径，首行最多 255 字节，不含换行。
-
-从调用目录向上找到最近的 `dx/scripts`，对应项目根作为应用脚本 cwd。最近标记损坏、不可读或缺少所请求入口时直接失败；不会执行外层同名命令。未发现内层标记才继续向上查找。
-
-`dx build admin --prod` 只运行 `dx/scripts/build`，脚本仍收到 `admin`、`--prod`。没有自动的二级命令查找、app 目录推断、默认 all 或构建编排。`start stack` 与 `start admin` 也调用同一个 start 文件，由应用选择服务。
-
-无参数和顶层 `--help` 显示帮助，`--version` 无需工程。`dx initial --help` 是内置帮助；其他命令后的 `--help` 交给应用，不由 dx 截获。
-
-## 环境
-
-**环境名称选择配置，执行位置是运行 dx 的当前机器。** 例如在开发电脑执行 `dx start admin --prod`，dx 读取该电脑项目根的 `.env.production`，再加载 `.env.production.local` 覆盖，设置 APP_ENV / NODE_ENV 为 production，并在该电脑调用 `dx/scripts/start` 启动 admin。它不表示到生产服务器运行，也不触发远程连接、发布或部署；`--staging` 等标志同理。在服务器执行时，当前机器就是那台服务器。
-
-应用 start 保持本机启动语义；需要远程部署时，由应用 deploy 等明确入口实现。进程访问哪些数据库或 API 取决于配置中的地址：本机运行仍可能连接远端资源，运行位置与资源位置应分别说明。
-
-从找到的项目根加载，优先级由低到高：
-
-```text
-继承环境变量 < .env.<environment> < .env.<environment>.local
-```
-
-这意味着 CI 注入的普通变量也可能被文件中的同名值覆盖。公开文件只放适合入库的默认值或明确占位符，真实值放入忽略的 local 文件或按项目方式注入；项目脚本自己校验必要值。
-
-环境选择按下列顺序：
-
-1. 命令后、第一个 `--` 前的环境标志；优先级依次为 `--prod`、`--staging`、`--dev`、`--test`、`--e2e`。建议调用方只使用一个。
-2. 调用者 APP_ENV，其次 NODE_ENV；都没有时为 development。选择名称转小写，dev/local 映射为 development；不支持的名称报错。
-
-| 选定环境 / APP_ENV | 注入的 NODE_ENV | 两层文件 |
-| --- | --- | --- |
-| development | development | .env.development、.env.development.local |
-| staging | production | .env.staging、.env.staging.local |
-| production | production | .env.production、.env.production.local |
-| test | test | .env.test、.env.test.local |
-| e2e | test | .env.e2e、.env.e2e.local |
-
-APP_ENV 和 NODE_ENV 在展开变量前确定，不允许文件重新设置。不从环境文件中读取 APP_ENV 来决定加载哪套文件。命令名本身不会改环境：未指定环境的 `dx test` 或 `dx build` 不会自动选择 test 或 production。
-
-文件缺失跳过，读取失败则停止；只修改传给应用的子进程环境。dotenv 负责引号、注释和多行值，dotenv-expand 按其语法展开同层已定义变量、前层和调用者变量。迁移旧手写解析或 shell source 时，应使用非敏感样例复核 `$`、引号、转义及依赖顺序，不能当作 shell 脚本执行。
-
-不加载通用 `.env` / `.env.local`、应用子目录文件或 `dx/config/env-layers.json`。`DX_CONFIG_DIR` 和顶层 `--config-dir` 不再选择工程或配置。选择环境的标志保留在 argv；`--` 后的标志只属于应用参数。
-
-## setup 的公共步骤
-
-必须先有合法 `dx/scripts/setup`。入口检查通过后，顺序为复制 → 环境加载 → 应用脚本。
-
-- 当前是 linked worktree 时，从 Git 登记的主工作目录递归复制所有以 `.local` 结尾的普通文件，含隐藏与被 Git 忽略的文件，按相对路径写入当前 Git worktree 根并保留文件权限。
-- 跳过已经存在的文件、目录和链接；不覆盖、不更新已有副本，不会在每次 start/build 时同步。
-- 跳过源符号链接、`.git` 元数据和嵌套 worktree；目标父路径必须是实际目录。失败停止应用 setup；已成功复制的文件保留，修复后可再次执行。
-- 主工作目录（含从其子目录调用）、非 Git 工程、bare 仓库下没有主 checkout 的 worktree 不复制。Git 不可用会报错。
-- 项目根若是 Git 根的子目录，复制目标仍是 Git worktree 根，环境加载位置仍是项目根。
-
-复制 `.env.local` 不代表会加载它；加载始终只认选定环境的两层文件。新 clone 不共享另一个 clone 的本地文件，也不会自动向远端下载凭据。
-
-## 进程与操作责任
-
-argv 逐项传递，空字符串、引号、空格、`--` 保留；dx 不拼接 shell 字符串。stdin/stdout/stderr 直接继承，应用退出码保留。
-
-脚本保持前台终端；dx 转发 SIGINT/SIGTERM，并保留应用最终信号或退出码。终端 Ctrl-C 可能与转发同时到达，应用应幂等清理自己启动的进程。dx 不监督任意后代或后台服务。
-
-单进程 Shell 包装优先使用 `exec`。多服务启动、端口冲突、工具版本、秘密校验、数据库确认和部署恢复均由应用完成；没有通用 `--yes`、`--dry-run` 或自动修复能力。

package/skills/dx-adopt/references/migrate-0.1.md

@@ -1,50 +0,0 @@
-# 从 0.1.x 迁移
-
-仅用于已有旧版调用的项目。0.2.0 起采用硬切换，接入使用 >=0.2.0 的实际已核验版本：旧命令表和内部 runner 不再执行，迁移的目标是把项目实际需要的行为放入应用脚本，而非重建旧 dx。
-
-## 先盘点，再替换
-
-检查项目真实使用的 `dx/config/commands.json`、环境层/策略配置、包脚本、CI、容器入口、Nx 等工具目标和项目已有实现。只记录环境文件路径与变量名，避免将秘密值复制进报告。旧版本实现只有在行为无法由项目源码解释时才按实际版本查证。
-
-建立一张迁移表，每项包含：旧入口与调用者、实际执行内容、环境、顺序/并发关系、安全条件、新入口/实现文件、验证方式与结果。不能仅把旧命令名改成新命令名；同一个 `dx build admin` 在新版本下也需要实际的 build 文件。
-
-## 旧能力的去向
-
-| 旧依赖或配置 | 新脚本入口应做什么 |
-| --- | --- |
-| commands.json 的 command、嵌套子命令和环境分支 | 对应顶层 dx/scripts 文件，内部自行解析目标与子命令，根据 APP_ENV 调用真实实现 |
-| concurrent、commands 引用、all/development 聚合 | 在项目脚本中明确任务成员、顺序/并发、失败传播与退出收尾 |
-| internal: pm2-stack、backend-artifact-deploy 等 | 直接使用项目工具完成原先需要的流程；不能保留 internal 字段期待 dx 执行 |
-| app、目标别名、自动推断目录、requiresPath/fileCommand | 在项目脚本验证目标和路径并按 argv 调用；旧占位符替换不再发生 |
-| env-layers.json、自定义环境路径、{app} 层 | 迁到标准两层，或由应用明确加载额外文件；通用 .env 和 .env.local 不参与 dx 加载 |
-| env-policy、requiredVars、占位符检查、dangerous/确认 | 由项目入口执行必要检查与确认；包括 allowRoot/allowSubdirGlobs 等布局规则，详见适配回归检查 |
-| ports、自动终止服务、重试、Prisma 自动生成 | 将必要准备放入 setup 或具体应用流程；启动失败不再由 dx 自动修复 |
-| Next/Nx 构建识别、强制 NODE_ENV、轮询变量 | 核对项目工具要求，在项目实现中显式设置；不要假定 dx 仍设置 NX_DAEMON 等变量 |
-| SDK 构建、制品上传、Vercel、回滚、版本注入 | 项目维护自己的构建/发布脚本和故障处理；dx 不再提供这些实现 |
-| dx-with-version-env、私有 lib import、旧 bin 路径 | 改成项目自己的实现及公开 dx 脚本入口，检查 package scripts、CI 和容器调用点 |
-| dx install、lint、clean、cache 等旧命令 | 按项目需要保留为自定义脚本，或把其调用者改成实际工具；标准安装准备可归入 setup |
-| --config-dir、DX_CONFIG_DIR、自定义根定位 | 在目标工程建立 dx/scripts 标记，调整调用 cwd；旧配置目录不再定义工程 |
-| 技能分发 | skills 与 dx initial 仍保留。不要把 initial 删除或误改为项目 setup |
-
-## 实施顺序
-
-1. 保留旧实现证据，完成迁移表。只清理已确认没有消费者的旧功能；需求不明确但仍被 CI 使用的行为先保留在项目侧。
-2. 创建必需的应用脚本及内部实现。使用实际工具命令，避免复制整套旧 dx 私有运行时。每条分支有成功、失败及参数处理行为；项目帮助应在业务操作前处理。
-3. 整理环境。原先的普通环境变量优先级、APP_ENV/NODE_ENV 关系、构建和测试环境逐项复核；以随技能的 [当前契约](dx-0.2-contract.md) 为准。已有 dotenv 包若仍被应用其他模块使用，应保留。
-4. 更新安装策略与调用者，进行本地/隔离验收。CI 与本地采用一致的版本策略（如全局 latest、最低 >=0.2.0），记录各自实际版本，保证创建脚本时的可执行权限入库。仅设置 CI secret 不足以证明未被文件同名值覆盖。
-5. 消费者和验证均切换后，删除无人使用的旧 dx 配置、包装和依赖，更新文档。保留 Prisma schema、PM2 ecosystem、Nx 配置等仍被项目脚本使用的工具文件。
-
-## 容易漏掉的行为
-
-- `dx build admin --prod` 中的 --prod 仍进入 build 的 argv。直接 `exec nx build "$@"` 可能把 dx 标志误传给 Nx；在项目解析层消费环境标志，正确处理 `--` 边界。
-- `.env.<环境>.local` 中已有值不会被基础 setup 更新；旧 worktree 需要同步新增配置时明确处理缺项，不能通过再次 setup 假定全部刷新。
-- 缺少环境文件不会让 dx 自行阻止数据库或部署。需要的变量、生产目标、不可逆操作和失败恢复须在应用中验证；不能删除原确认条件后裸调用工具。
-- `start stack` 不再隐含 PM2 重置或端口清理。启动哪些服务、是否清理冲突端口、如何退出由项目确定。
-- 测试文件参数不再由 dx 的 fileCommand 模板转换；验证文件和目录范围都传给了正确测试目标。
-- 新的 NODE_ENV 映射与命令名无关。旧项目若依赖“build 一定 production”或“test 一定 test”，调整调用参数或项目工具逻辑并测试。
-
-## 完成条件
-
-按 [适配回归检查](adoption-regressions.md) 验证迁移涉及的分支，特别是测试层独立性、构建产物、环境布局和后代进程回收。
-
-迁移表中每个实际使用的旧能力都已实现、替换或在用户授权下明确取消；无未解释的旧私有接口与配置消费者；根目录、子目录、fresh clone/worktree 和 CI 的安装与调用方式明确。报告实际验证结果，不能把假脚本返回成功或未执行的部署写成迁移完成。