@kevlns/ship-cli 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,25 @@
+# ship-cli Agent 指导
+
+用途：校验已构建游戏，执行 SteamPipe 上传、微信小游戏扫码预览与开发版上传。首次调用先读本规范并运行 ship-cli doctor --json；检查 ok 和所有 fail 项。doctor 离线报告退出 0 不代表在线账号可用。
+
+## 顺序
+
+1. 选择正确工程，使用 --project <dir>；路径基准为配置所在目录。先 config validate；初次 config init，填写真实 AppID / 产物路径，只保留使用的平台。
+2. Steam：steam vdf --preview 检查配置，steam preview 生成本地清单，steam test --write-appid 检查文件；授权上传后 steam push。显式 --set-live 才设置测试分支，default 自动发布拒绝执行。
+3. 微信：wx validate 校验结构和源码预算；wx preview 返回实际二维码，展示给用户；授权上传后 wx push --version <text> 创建开发版。体验版、提审、发布在后台处理。
+
+## 契约
+
+- Steam 需要 steamcmd、构建账号及 App / Depot 权限。仅读取 SHIP_STEAM_*；免密需有效缓存。显式工具路径失效时失败，不切换其他安装。
+- 微信工程安装 miniprogram-ci@2.1.31，支持 >=2.1.31 <3。私钥通过 SHIP_WX_PRIVATE_KEY 或 privateKeyPath 指定，必须在产物之外。
+- 只支持 schema 的明确字段，拒绝 ciArgs 等未知配置。setting 默认 useProjectConfig=true，robot 为数字 1–30。
+- 微信大小为 filtered-source-estimate，不能称为实际编译包大小。上传预算为主包 4 MiB、独立分包 4 MiB、总包 30 MiB；preview 扩展选项不改变上传限制。
+- Steam preview 不上传；微信 preview 调用平台服务生成二维码。二维码默认在 build/ship-preview 下，返回绝对路径，不覆盖已有文件。
+- 无完整完成记录必须失败；不能用普通 Success 或退出 0 推断上传成功。日志、进度和结果脱敏，目录穿越、产物链接、Steam 缓存交叠拒绝处理。
+- 不覆盖已有配置；config init --force 仅在用户授权覆盖时使用。不执行引擎构建、账号注册或正式发布。
+
+## 配套
+
+同一 npm prefix 安装后通过 v-cli ship 执行；先 v-cli agent docs ship，agent describe ship --json 获取清单。随包 v-cli skill 提供发现入口，通过 v-cli agent init 同步。
+
+维护运行 npm run check 与 npm run test:package。官方依据见随包 docs/research/steam.md、docs/research/wechat-minigame.md。npm 发布或真实平台上传须在相应用户任务授权内执行。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kevlns
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# ship-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+校验已经构建好的游戏，生成 SteamPipe 配置，执行 Steam 上传、微信小游戏预览与开发版上传。引擎构建、账号配置和正式发布由外部流程完成。
+
+## 安装与发现
+
+Node.js 20 及以上。npm 安装：`npm install -g @kevlns/ship-cli`。源码打包安装：
+
+```bash
+npm ci
+npm run check
+npm pack
+npm install -g ./kevlns-ship-cli-0.1.0.tgz
+ship-cli --version
+```
+
+v-cli 已注册 ship 为官方可选 peer 插件。将两者安装在同一 npm prefix 后自动发现：
+
+```bash
+v-cli plugin list --json
+v-cli agent docs ship
+v-cli agent describe ship --json
+v-cli ship --help
+```
+
+## 使用流程
+
+在游戏仓库执行 config init，编辑真实 AppID、产物路径，只保留使用的平台配置。路径以 ship.config.json 所在目录为基准；产物位于工程内，私钥和外部工具可用绝对路径。默认向上查找配置，--project <dir> 显式选择工程。
+
+```bash
+ship-cli config validate --json
+ship-cli doctor --json
+```
+
+doctor 离线输出逐项状态，退出 0 表示报告生成；查看 ok 和 fail 项确认就绪，不能据此判断在线账号权限。模板含两个平台，不使用的平台应删除。
+
+Steam：
+
+```bash
+ship-cli steam vdf --preview
+ship-cli steam preview --desc "local rehearsal"
+ship-cli steam test --write-appid
+ship-cli steam push --desc "0.3.7 nightly" --set-live beta
+ship-cli steam open builds
+```
+
+vdf 只写配置；preview 生成本地清单而不上传；test 检查 AppID、API 库与已配置可执行文件，不能替代启动游戏；push 上传，显式 --set-live 才设置测试分支。default 自动发布拒绝执行。
+
+微信：在游戏工程安装 npm i -D miniprogram-ci@2.1.31。
+
+```bash
+ship-cli wx validate --json
+ship-cli wx preview --robot 1 --json
+ship-cli wx push --version 1.0.0 --desc "fix: login loop" --robot 1 --json
+ship-cli wx open mp
+```
+
+validate 校验结构、配置一致性及过滤后的源码预算，默认主包 / 独立分包 / 总包 4 / 4 / 30 MiB。源码统计不是编译包大小，SDK 返回的编译信息保留在结果中。preview 调用微信服务生成二维码，JSON 返回绝对路径；push 在离线门禁通过后创建开发版本。体验版、提审、发布在后台人工完成。
+
+## 配置
+
+schema 随包提供于 schemas/ship-config.schema.json，未知字段拒绝加载。
+
+wechat 支持 appid、projectPath、robot、privateKeyPath、ignores、setting、bigPackageSizeSupport、timeoutMs。setting 默认 useProjectConfig=true，支持 es6、es7、minify、minifyJS、codeProtect、autoPrefixWXSS；bigPackageSizeSupport 只用于 preview。robot 为整数 1–30，timeoutMs 范围 1000–3600000。
+
+| 环境变量 | 用途 |
+| --- | --- |
+| SHIP_STEAMCMD | steamcmd 路径，优先于配置 |
+| SHIP_STEAM_USERNAME | Steam 构建账号 |
+| SHIP_STEAM_PASSWORD | 密码，缓存免密时可省略 |
+| SHIP_STEAM_TOTP | 本次 Guard 码 |
+| SHIP_STEAM_TOTP_SECRET | base64 共享密钥，用于生成 Guard 码 |
+| SHIP_STEAM_CONFIG_VDF | base64 免密缓存配置 |
+| SHIP_WX_PRIVATE_KEY | 微信上传私钥路径，优先于配置 |
+
+私钥与二维码必须位于微信产物之外。二维码默认 build/ship-preview/<随机标识>/qr.png，显式路径必须为新文件。Steam 缓存与产物不可交叠，产物链接拒绝处理；凭据不写入配置，日志和进度脱敏。
+
+执行命令的 --json 成功带 ok=true，失败带 ok=false 与 error.code / message / details / fix / docs；doctor 的 ok 表示体检状态。帮助、工具版本为文本。退出码：0 成功或报告已生成，1 参数 / 配置 / 内容校验拒绝，2 前置条件缺失，3 Steam 执行失败，4 微信 SDK 失败。未知完成结果按失败处理。
+
+## 维护
+
+npm run check 覆盖构建、类型、测试、lint、打包护栏；npm run test:package 对真实 tgz 隔离安装验证。prepack 自动构建，安装包携带当前代码、schema、插件清单、Agent 规范及官方调研文档。CI 配置 Windows / Linux / macOS 与 Node 20 / 22。
+
+依据与实现边界见 [Steam](docs/research/steam.md)、[微信小游戏](docs/research/wechat-minigame.md)。