android-publisher-cli 0.0.0-stage → 0.2.0-dev

package/docs/mac-cli-delivery.md

@@ -0,0 +1,36 @@
+# 维护者：npm 构建与分发
+
+本页供检查 npm 包的维护者使用。包内包含编译后的 JavaScript 和离线文档。使用者需要安装 [`.node-version`](../.node-version) 指定的 Node.js；npm 包不包含 Node.js、Android SDK 或 JDK。
+
+## 构建并验收
+
+在仓库根目录安装固定依赖，并运行完整检查：
+
+```sh
+npm ci --ignore-scripts
+PUBLISHER_REQUIRE_ANDROID_TESTS=1 npm run check
+npm pack --dry-run --json
+```
+
+最后一条命令列出实际包文件。应看到 `build/`、文档、许可证和 `package.json`。检查列表里没有凭据、APK、状态库、测试私钥或本机路径。npm 包不会运行安装脚本。
+
+需要离线交付时，可以生成 tarball 并保存摘要。下面以 `0.2.0` 为例：
+
+```sh
+mkdir -p dist
+npm pack --pack-destination dist
+cd dist
+shasum -a 256 android-publisher-cli-0.2.0.tgz \
+  > android-publisher-cli-0.2.0.tgz.sha256
+shasum -a 256 -c android-publisher-cli-0.2.0.tgz.sha256
+```
+
+核对输出为 `OK`。安装实际 tarball，再运行 `android-release version --json` 和 `android-release doctor`。CI 也会在独立前缀安装已检查的 tarball，确认命令可运行。
+
+## 分发边界
+
+tarball 没有原生可执行文件，因此旧版 macOS `codesign`、公证和安装脚本不再适用。包内包含 MIT 许可证和[第三方声明](../THIRD_PARTY_NOTICES.md)。Node.js 与 Android 工具由使用者分别安装，并遵守各自许可。
+
+首次预览版由维护者手工发布，用于占用 npm 包名并配置 Trusted Publisher。后续版本由 [publish-npm.yml](../.github/workflows/publish-npm.yml) 发布。工作流安装固定依赖、运行完整检查、打包、独立安装并核对 `android-release`，最后发布同一份 tarball。预发布版本使用 `next` 标签；正式版本使用 `latest`。真实渠道凭据和 APK 不能进入 npm 包、CI 或 GitHub 发布附件。
+
+同一版本号只能发布一次。内容改变时，先更新版本号与 `package-lock.json`，再生成新包。版本 PR、标签和 npm 发布的顺序见[版本发布](release-process.md)。

package/docs/release-process.md

@@ -0,0 +1,51 @@
+# 维护者：版本发布
+
+本流程将 CLI 发布到 npm 注册表，不会向 Android 商店提交应用。构建与检查命令见[构建与分发](mac-cli-delivery.md)。
+
+## 首次占用包名
+
+npm 要求包先存在于注册表，才能配置 Trusted Publisher。本仓库当前版本是 `0.2.0-dev`。首次合并发布工作流后，由拥有 npm 包名的维护者手工发布这个预览版。
+
+先确认 `main` 顶端提交的 CI `check` 已通过，再在同一提交运行：
+
+```sh
+git switch main
+git pull --ff-only origin main
+npm ci --ignore-scripts
+PUBLISHER_REQUIRE_ANDROID_TESTS=1 npm run check
+npm pack --dry-run --json
+mkdir -p dist
+npm pack --pack-destination dist
+npm login
+npm publish ./dist/android-publisher-cli-0.2.0-dev.tgz --access public --tag next
+```
+
+`npm login` 和首次发布由维护者在终端完成，按 npm 提示进行双重验证。发布前核对文件清单、包名和版本。发布后运行 `npm view android-publisher-cli@0.2.0-dev version` 核对注册表。这个版本公开后不能覆盖，也无需为它创建 GitHub Release。
+
+若包名已被他人占用，先修改包名和工作流，再发布。
+
+包存在后，在 npm 的包设置中配置 Trusted Publisher。填写 GitHub 用户 `wangyiliangnet`、仓库 `android-publisher-cli` 和工作流文件名 `publish-npm.yml`，并允许 `npm publish`。工作流使用 OIDC 短期凭据，不需要 `NPM_TOKEN`。
+
+新建 Trusted Publisher 后，应在 2 天内完成一次工作流发布；过期后需删除并重建配置。GitHub 仓库的 Actions 设置还须允许工作流创建 PR。版本工作流需要 `contents: write` 和 `pull-requests: write` 权限。
+
+## 准备版本
+
+在 GitHub Actions 的 [Prepare npm release](../.github/workflows/prepare-npm-release.yml) 页面，从 `main` 运行工作流。输入更高的 SemVer（不带 `v`）和一行公开更新说明。当前 `0.2.0-dev` 的下一个正式版本可填 `0.2.0`。
+
+工作流会更新 `package.json`、`package-lock.json` 和 [CHANGELOG.md](../CHANGELOG.md)，并创建版本 PR。不能重复使用已有版本号。
+
+审阅 PR 中的版本号和更新记录。按实际变化补充状态兼容性、已知限制和安装要求。等待 PR 的必需 CI `check` 通过后再合并。
+
+由 `GITHUB_TOKEN` 创建的 PR 可能需要维护者在 GitHub 上批准工作流运行。
+
+## 发布到 npm
+
+版本 PR 合并后，确认 `main` 顶端提交的 CI `check` 通过。在 GitHub Releases 中建立 `vVERSION`，目标选当前 `main` 顶端提交。说明中列出 Node.js 要求、状态兼容性和六个渠道的真实账号验证情况。
+
+预发布版本（如 `0.2.0-rc.1`）须勾选“Set as a pre-release”；正式版本不要勾选。发布 GitHub Release 后，[publish-npm.yml](../.github/workflows/publish-npm.yml) 会核对标签、包版本、锁文件和 `main` 提交。核对通过后，工作流运行完整检查，并发布已检查的 tarball。若 `main` 已前进，先评估新增改动并使用新版本号。
+
+工作流成功后，在 npm 上核对 `android-publisher-cli@VERSION` 和对应标签。安装该版本，运行 `android-release version --json`，检查包内文档。
+
+发布失败时先看 Actions 日志和 npm 中是否已有同版本。npm 已接受的版本不能覆盖，修复内容须使用新版本号。
+
+PR 和 npm 发布检查只说明对应代码与包通过测试，不代表真实商店账号已验证，也不授权应用提审。

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "android-publisher-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0-dev",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wangyiliangnet/android-publisher-cli.git"
+  },
+  "homepage": "https://github.com/wangyiliangnet/android-publisher-cli#readme",
+  "bugs": "https://github.com/wangyiliangnet/android-publisher-cli/issues",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "files": ["build", "docs", ".node-version", "README.md", "CONTRIBUTING.md", "AGENTS.md", "CHANGELOG.md", "LICENSE", "LICENSE.zh-CN.md", "THIRD_PARTY_NOTICES.md"],
+  "bin": {
+    "android-release": "./build/cli.js"
+  },
+  "engines": {
+    "node": "24.22.0",
+    "npm": "11.19.1"
+  },
+  "packageManager": "npm@11.19.1",
+  "scripts": {
+    "build": "rm -rf build && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "pack:check": "npm run check && npm pack --dry-run --json",
+    "check": "npm run typecheck && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.5",
+    "typescript": "7.0.2"
+  }
+}