@kevlns/ship-cli 0.0.0-stage → 0.1.0

package/docs/research/steam.md

@@ -0,0 +1,14 @@
+# Steam 官方契约
+
+核验日期：2026-10-09。依据 Valve [Uploading to Steam](https://partner.steamgames.com/doc/sdk/uploading)、[Steamworks API](https://partner.steamgames.com/doc/sdk/api)、[Depots](https://partner.steamgames.com/doc/store/application/depots)。
+
+- SteamPipe 通过 steamcmd 的 +login / +run_app_build / +quit 构建上传已生成的产物。ship-cli 不执行引擎构建。
+- AppBuild VDF 指定 AppID、Desc、ContentRoot、BuildOutput、Preview、SetLive、Depots；DepotBuild VDF 指定 DepotID、ContentRoot、FileMapping、FileExclusion。
+- Preview=1 产生本地日志和清单，不上传。SetLive 仅用于测试分支，default 分支必须在 Steamworks 后台处理。
+- BuildOutput 保存缓存和日志，必须与上传产物分离；工具校验真实路径，包括 Windows junction，拒绝目录交叠和产物链接。
+- Steam API 分发库为 Windows 的 steam_api.dll / steam_api64.dll、Linux 的 libsteam_api.so、macOS 的 libsteam_api.dylib。steam test 检查文件与 AppID，不启动游戏，也不能证明 SDK 初始化成功。
+- 本地绕过 Steam 客户端启动时通过 steam_appid.txt 提供 AppID；正常从 Steam 启动的发行包不依赖该文件。
+
+Valve 没有承诺稳定的机器可读日志协议。工具采取保守判定：非零退出、错误日志、登录 Guard 提示均失败；成功记录须包含当前 AppID 的 Successfully finished ... build，真实上传还须包含 BuildID。无法确定时返回 STM_BUILD_UNKNOWN_OUTCOME。这条日志解析规则仍需真实账号日志验证。
+
+工具仅读取 SHIP_STEAM_*。免密登录需要有效的 steamcmd 缓存；SHIP_STEAM_CONFIG_VDF 提供 base64 缓存，拒绝覆盖不同的已有文件。缓存存在不代表账号或权限有效。进度和日志脱敏包括跨输出块拆分的密码及运行时生成的 Guard 码；执行超时为一小时。

package/docs/research/wechat-minigame.md

@@ -0,0 +1,31 @@
+# 微信小游戏官方契约
+
+核验日期：2026-10-09。官方页面直接获取成功，同时核对微信 SDK README 和 npm registry。
+
+## 官方依据
+
+- [代码包](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/code-package.html)
+- [使用分包](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/subPackage/useSubPackage.html)
+- [独立分包](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/independent-sub-packages.html)
+- [Worker](https://developers.weixin.qq.com/minigame/dev/guide/base-ability/workers)
+- [game.json](https://developers.weixin.qq.com/minigame/dev/reference/configuration/app.html)
+- [project.config.json](https://developers.weixin.qq.com/miniprogram/dev/devtools/projectconfig.html)
+- [官方 miniprogram-ci README](https://github.com/wechat-miniprogram/miniprogram-ci-dist/blob/master/README.md)
+
+## 结构与体积
+
+上传默认主包 4 MiB、每个独立分包 4 MiB、总包 30 MiB；普通分包没有单独大小上限。开放数据域计入主包。目录分包根目录需要 game.js，单 JS 文件也可以成为分包。
+
+官方示例 /moduleA/ 是小游戏内路径，工具规范为 moduleA，不当作操作系统绝对路径；拒绝系统盘符、网络路径、目录穿越、根目录交叠。Worker 支持字符串目录以及 {path, isSubpackage:true}；分包能力从基础库 2.27.3 起提供，不属于 independent 分包。
+
+离线统计支持 packOptions 的 file / folder / suffix / prefix / regexp / glob，include 优先于 ignore；SDK Project ignores 独立生效，默认 node_modules/**/*。统计标记 filtered-source-estimate，源码编译压缩后大小会变化。wx validate 是保守离线预算门禁，不代表平台实际编译包大小；最终上传结果由 SDK 和服务器决定。
+
+## SDK 契约
+
+使用 new ci.Project({appid,type:'miniGame',projectPath,privateKeyPath,ignores})，以及 ci.upload / ci.preview 的 Node API。robot 为 1–30 的数字；setting 默认 useProjectConfig=true。配置使用明确布尔字段，不存在 ciArgs 透传。preview 使用 qrcodeFormat=image 与实际 qrcodeOutputDest。
+
+bigPackageSizeSupport 只用于 preview，不改变上传限制，也不承诺小游戏具有固定 8 MiB 预览额度。registry 当前可安装 2.1.31，官方 README 版本列表已到 2.1.48，两者不能混用；工具支持 >=2.1.31 <3。
+
+SDK 必须返回有效完成记录；退出 0 不等于完成。subPackageInfo 可选，原样保留在 JSON 结果中。preview 还必须实际生成 PNG 二维码。私钥须为可解析 PEM，放在上传目录之外；二维码也在产物之外，默认 build/ship-preview/<随机标识>/qr.png，拒绝覆盖已有文件。执行默认超时 15 分钟，可通过 timeoutMs 配置。
+
+upload 创建开发版本；体验版、体验者、提审和发布在微信后台处理。preview 调用微信服务生成扫码入口，不创建开发版本，也不是离线预演。

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@kevlns/ship-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Cross-platform game shipping CLI. Validate, package and push builds to game platforms (Steam via steamcmd VDF builds, WeChat mini games via miniprogram-ci). Never publishes to players on its own.",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "bin": {
+    "ship-cli": "dist/cli.mjs"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "schemas/",
+    "v-cli.plugin.json",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE",
+    "docs/research/"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src tests scripts",
+    "check": "npm run build && npm run typecheck && npm run test && npm run lint && npm run pack:guard",
+    "pack:guard": "node scripts/pack-guard.mjs",
+    "test:package": "node scripts/test-package-install.mjs",
+    "prepack": "npm run build",
+    "pretest": "npm run build"
+  },
+  "keywords": [
+    "game",
+    "shipping",
+    "steam",
+    "steamcmd",
+    "steampipe",
+    "wechat",
+    "minigame",
+    "miniprogram-ci",
+    "publish"
+  ],
+  "author": "kevlns",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "ajv": "8.20.0",
+    "commander": "12.1.0",
+    "minimatch": "9.0.9"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.6.0",
+    "@types/node": "20.19.0",
+    "eslint": "9.6.0",
+    "tsup": "8.5.1",
+    "typescript": "5.6.3",
+    "typescript-eslint": "8.71.1",
+    "vitest": "4.1.11"
+  },
+  "vCli": {
+    "manifest": "v-cli.plugin.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kevlns/ship-cli.git"
+  },
+  "homepage": "https://github.com/kevlns/ship-cli#readme",
+  "bugs": {
+    "url": "https://github.com/kevlns/ship-cli/issues"
+  }
+}

package/schemas/ship-config.schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/kevlns/ship-cli/schemas/ship-config.schema.json",
+  "title": "ship-cli project configuration (ship.config.json)",
+  "description": "Non-secret, repo-committed configuration for shipping a game project to distribution platforms. Secrets (Steam credentials, WeChat upload keys) are never stored here: they come from environment variables or user-level key files referenced by path.",
+  "type": "object",
+  "required": ["schemaVersion"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "const": 1,
+      "description": "Config schema version. Only 1 is supported."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional human-readable project name used in output."
+    },
+    "steam": {
+      "$ref": "#/definitions/steam"
+    },
+    "wechat": {
+      "$ref": "#/definitions/wechat"
+    },
+    "limits": {
+      "$ref": "#/definitions/limits"
+    }
+  },
+  "definitions": {
+    "relativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?![/\\\\])(?![A-Za-z]:)(?!.*(?:^|[/\\\\])\\.\\.(?:[/\\\\]|$))(?!.*[\\u0000-\\u001f]).+$",
+      "description": "Relative path, forward or back slashes, no leading slash, no '..' segments."
+    },
+    "steam": {
+      "type": "object",
+      "required": ["appId", "contentRoot", "buildOutput", "depots"],
+      "additionalProperties": false,
+      "properties": {
+        "appId": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Steam AppID of the base application."
+        },
+        "contentRoot": {
+          "$ref": "#/definitions/relativePath",
+          "description": "Root directory of built content. Resolved against the config file location."
+        },
+        "buildOutput": {
+          "$ref": "#/definitions/relativePath",
+          "description": "steamcmd BuildOutput directory (logs + chunk cache). Must NOT be inside contentRoot."
+        },
+        "executable": {
+          "$ref": "#/definitions/relativePath",
+          "description": "Optional main executable relative to contentRoot, checked by 'steam test'."
+        },
+        "steamcmdPath": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional explicit steamcmd executable path. Env SHIP_STEAMCMD wins over this."
+        },
+        "depots": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/depot"
+          }
+        }
+      }
+    },
+    "depot": {
+      "type": "object",
+      "required": ["id", "source"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Depot ID. Convention: base app depots start at appId+1."
+        },
+        "source": {
+          "$ref": "#/definitions/relativePath",
+          "description": "Directory inside contentRoot whose CONTENTS map to the depot root. Use \".\" for the whole contentRoot."
+        },
+        "exclusions": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "FileExclusion glob patterns for this depot, e.g. *.pdb, *_BurstDebugInformation_DoNotShip*."
+        }
+      }
+    },
+    "wechat": {
+      "type": "object",
+      "required": ["appid", "projectPath"],
+      "additionalProperties": false,
+      "properties": {
+        "appid": {
+          "type": "string",
+          "pattern": "^wx[0-9a-f]{16}$",
+          "description": "WeChat mini game AppID."
+        },
+        "projectPath": {
+          "$ref": "#/definitions/relativePath",
+          "description": "Mini game project directory (contains game.json / game.js / project.config.json)."
+        },
+        "robot": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 30,
+          "default": 1,
+          "description": "miniprogram-ci robot slot (1-30). Different robots keep separate dev-version records in the MP backend."
+        },
+        "privateKeyPath": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Path to the code-upload private key file downloaded from the MP backend. Env SHIP_WX_PRIVATE_KEY / WX_UPLOAD_KEY wins over this. May contain '~'."
+        },
+        "ignores": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "default": ["node_modules/**/*"],
+          "description": "Glob rules passed directly to ci.Project and used by source-size estimation."
+        },
+        "setting": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "useProjectConfig": {
+              "type": "boolean"
+            },
+            "es6": {
+              "type": "boolean"
+            },
+            "es7": {
+              "type": "boolean"
+            },
+            "minify": {
+              "type": "boolean"
+            },
+            "minifyJS": {
+              "type": "boolean"
+            },
+            "codeProtect": {
+              "type": "boolean"
+            },
+            "autoPrefixWXSS": {
+              "type": "boolean"
+            }
+          }
+        },
+        "bigPackageSizeSupport": {
+          "type": "boolean",
+          "default": false,
+          "description": "SDK preview-only option; does not alter upload limits."
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 3600000,
+          "default": 900000
+        }
+      }
+    },
+    "limits": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "WeChat package size limits in bytes (1024-based M). Defaults follow official rules as of 2026-10; override only when WeChat changes them.",
+      "properties": {
+        "wxMainBytes": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "wxIndependentSubpackageBytes": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "wxTotalBytes": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    }
+  }
+}