@viceme-ai/cli 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.2.1] - 2026-07-20
+
+### Fixes
+
+- add verified binary mirror fallback (`efb0d83`)
+
+### Other Changes
+
+- add Feishu pull request notifications (`b6174b1`)
+
 ## [0.2.0] - 2026-07-19
 
 ### Features

package/README.md

@@ -50,7 +50,7 @@ npm install --global @viceme-ai/cli
 viceme install
 ```
 
-Both methods persist the npm launcher, download the matching checksum-verified Go binary, and install the bundled Viceme Agent Skill. They default to the China service. For the international service:
+Both methods persist the npm launcher, download the matching checksum-verified Go binary, and install the bundled Viceme Agent Skill. Binary downloads try GitHub Release first, then a configured non-default npm registry's `/-/binary/viceme-cli/` mirror, and finally the public npmmirror binary mirror. The launcher uses system `curl`, so standard proxy environment variables are honored. They default to the China service. For the international service:
 
 ```bash
 npx --yes @viceme-ai/cli@latest install --region global
@@ -269,7 +269,7 @@ Determine command success from the process exit code or `ok == true`. A successf
 - **Credential isolation** — credentials stay in the OS keychain and are namespaced by region.
 - **Immutable inputs** — inspection binds publication to an immutable source snapshot rather than re-reading a floating URL later.
 - **Bounded waiting** — `job wait` has a maximum duration and returns the latest durable state without cancelling the workflow.
-- **Verified distribution** — the npm launcher downloads the binary for its exact package version and verifies the published SHA-256 checksum before activation.
+- **Verified distribution** — the npm launcher downloads the binary for its exact package version from GitHub or a binary mirror and verifies it against the checksum manifest bundled in the npm package before activation.
 
 ## Diagnose and Update
 

package/README.zh.md

@@ -50,7 +50,7 @@ npm install --global @viceme-ai/cli
 viceme install
 ```
 
-两种方式都会持久化 npm 启动器、下载匹配且通过校验和验证的 Go 二进制文件，并安装随包发布的 Viceme Agent Skill。默认使用中国区服务。使用国际区服务：
+两种方式都会持久化 npm 启动器、下载匹配且通过校验和验证的 Go 二进制文件，并安装随包发布的 Viceme Agent Skill。二进制下载依次尝试 GitHub Release、用户配置的非默认 npm registry 的 `/-/binary/viceme-cli/` 镜像，最后回退到公共 npmmirror binary 镜像。启动器使用系统 `curl`，因此会遵循标准代理环境变量。默认使用中国区服务。使用国际区服务：
 
 ```bash
 npx --yes @viceme-ai/cli@latest install --region global
@@ -269,7 +269,7 @@ CLI 执行错误写入 **stderr**，退出码非零：
 - **凭证隔离** — 凭证保存在操作系统密钥链中，并按区域隔离。
 - **不可变输入** — inspect 会把发布绑定到不可变来源快照，而不是在之后重新读取浮动 URL。
 - **有界等待** — `job wait` 有最大等待时间；超时后返回最新持久化状态，不会取消工作流。
-- **可信分发** — npm 启动器下载与其准确包版本匹配的二进制文件，并在启用前验证发布的 SHA-256 校验和。
+- **可信分发** — npm 启动器从 GitHub 或 binary 镜像下载与其准确包版本匹配的二进制文件，并在启用前使用 npm 包内置的校验清单验证 SHA-256。
 
 ## 诊断与更新
 

package/checksums.txt

@@ -0,0 +1,6 @@
+d22d97438aa887b238ef6c506ccd19ffe049877754660d00e114069079ca2151  viceme_0.2.1_darwin_amd64
+2157e6ccdbe76c6404e238fb2d04ea17c79289a1b712bfff42ddc8b1acdb7db6  viceme_0.2.1_darwin_arm64
+96dc6b38b609639e3111bdbfcc9bf0bcedf3fa6a0c66e3b2b2d769261a6acc84  viceme_0.2.1_linux_amd64
+7a9b0576ee36e9eab893f84669ca8cb6bd58d4bfc50a58054356c3863f710570  viceme_0.2.1_linux_arm64
+b825703ce462985bf8810b8c386e39b0e50ca6b600f301cec7a6822309e101b2  viceme_0.2.1_windows_amd64.exe
+cea8060b6f1f7f5a1c6bf44b787cd1ca5312c9b1f4e585b0f8bef325d6f748e0  viceme_0.2.1_windows_arm64.exe

package/docs/releasing.md

@@ -28,7 +28,8 @@ files, create tags, write changelog entries, or run npm commands locally.
 8. A maintainer reviews and merges that same Release PR.
 9. `Release CLI and npm launcher` tags the exact reviewed `dev` head, reruns
    the quality gates, builds six platform binaries and six checksums, creates
-   the GitHub Release, publishes the npm launcher, and then sends an
+   the GitHub Release, bundles those exact checksums into the npm launcher,
+   publishes it, and then sends an
    AI-generated release summary to the release notification group in Feishu.
 
 ## One-time repository setup
@@ -73,6 +74,14 @@ its first release, add a repository secret named `NPM_TOKEN` containing a
 granular automation token limited to `@viceme-ai/cli` publication. Remove that
 secret after the package exists and trusted publishing is confirmed.
 
+The npm tarball contains `checksums.txt`, generated from the six immutable
+GitHub Release checksum assets immediately before publication. The launcher
+uses that bundled manifest as its trust root whether the matching binary is
+transported by GitHub Release, a configured npm registry binary mirror, or the
+public npmmirror binary mirror. Registering `viceme-cli` with cnpmcore enables
+the public `/-/binary/viceme-cli/` mirror; it does not create another npm
+package.
+
 `GITHUB_TOKEN` is provided by Actions and is used only to maintain the Release
 PR. `RELEASE_APP_ID` and `RELEASE_APP_PRIVATE_KEY` authenticate the narrowly
 scoped Release App. `NPM_TOKEN` is optional and should only be retained when the

package/npm/lib/installer.mjs

@@ -1,10 +1,15 @@
+import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { access, chmod, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-const RELEASE_BASE_URL = "https://github.com/ViceMe-AI/cli/releases/download";
+const GITHUB_RELEASE_BASE_URL = "https://github.com/ViceMe-AI/cli/releases/download";
+const NPM_REGISTRY_URL = "https://registry.npmjs.org";
+const NPMMIRROR_BINARY_BASE_URL =
+  "https://registry.npmmirror.com/-/binary/viceme-cli";
+const CHECKSUMS_URL = new URL("../../checksums.txt", import.meta.url);
 const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 const GENERATIONS_DIRECTORY = "generations";
 const GENERATION_PREFIX = "generation-";
@@ -40,14 +45,40 @@ export function releaseAssetName(version, platform, architecture) {
   return `viceme_${version}_${target.operatingSystem}_${target.architecture}${target.extension}`;
 }
 
+export function binaryDownloadURLs({
+  packageVersion,
+  asset,
+  environment = process.env,
+  sourceBaseURLs,
+  allowInsecureURL = false,
+}) {
+  const bases = sourceBaseURLs ?? defaultBinarySourceBaseURLs(environment);
+  const urls = [];
+  const seen = new Set();
+  for (const base of bases) {
+    const parsed = parseDownloadBaseURL(base, allowInsecureURL);
+    const normalizedBase = parsed.href.replace(/\/$/, "");
+    const url = `${normalizedBase}/v${packageVersion}/${asset}`;
+    if (!seen.has(url)) {
+      seen.add(url);
+      urls.push(url);
+    }
+  }
+  if (urls.length === 0) {
+    throw new Error("no valid binary download source is configured");
+  }
+  return urls;
+}
+
 export async function ensureBinary({
   packageVersion,
   environment = process.env,
   platform = process.platform,
   architecture = process.arch,
-  fetchImplementation = globalThis.fetch,
-  releaseBaseURL = RELEASE_BASE_URL,
+  downloadImplementation = downloadWithCurl,
+  sourceBaseURLs,
   cacheDirectory,
+  checksumsDocument,
   allowInsecureURL = false,
 }) {
   if (environment.VICEME_BINARY_PATH) {
@@ -55,8 +86,8 @@ export async function ensureBinary({
     await access(overridden, constants.X_OK);
     return overridden;
   }
-  if (typeof fetchImplementation !== "function") {
-    throw new Error("Node.js fetch support is required");
+  if (typeof downloadImplementation !== "function") {
+    throw new Error("a binary download implementation is required");
   }
   const asset = releaseAssetName(packageVersion, platform, architecture);
   const root = cacheDirectory ?? defaultCacheDirectory(environment, platform);
@@ -67,18 +98,23 @@ export async function ensureBinary({
     return cached;
   }
   await mkdir(generationsDirectory, { recursive: true, mode: 0o700 });
-  const versionURL = `${releaseBaseURL}/v${packageVersion}`;
-  const checksumURL = `${versionURL}/${asset}.sha256`;
-  const binaryURL = `${versionURL}/${asset}`;
-  const [checksumDocument, binary] = await Promise.all([
-    download(checksumURL, fetchImplementation, allowInsecureURL),
-    download(binaryURL, fetchImplementation, allowInsecureURL),
-  ]);
-  const expectedChecksum = parseChecksum(checksumDocument.toString("utf8"));
-  const actualChecksum = digest(binary);
-  if (actualChecksum !== expectedChecksum) {
-    throw new Error(`checksum mismatch for ${asset}`);
-  }
+  const checksumSource =
+    checksumsDocument ?? (await readFile(CHECKSUMS_URL, "utf8"));
+  const expectedChecksum = checksumForAsset(checksumSource, asset);
+  const urls = binaryDownloadURLs({
+    packageVersion,
+    asset,
+    environment,
+    sourceBaseURLs,
+    allowInsecureURL,
+  });
+  const binary = await downloadVerifiedBinary({
+    asset,
+    expectedChecksum,
+    urls,
+    downloadImplementation,
+    allowInsecureURL,
+  });
 
   // If another cold start finished while this process downloaded, reuse its
   // complete immutable generation. Duplicate downloads are harmless; shared
@@ -122,6 +158,130 @@ export async function ensureBinary({
   return installedBinary;
 }
 
+function defaultBinarySourceBaseURLs(environment) {
+  const sources = [GITHUB_RELEASE_BASE_URL];
+  const configuredRegistry =
+    environment.npm_config_registry ?? environment.NPM_CONFIG_REGISTRY;
+  const registryBinaryBase = customRegistryBinaryBaseURL(configuredRegistry);
+  if (registryBinaryBase) {
+    sources.push(registryBinaryBase);
+  }
+  sources.push(NPMMIRROR_BINARY_BASE_URL);
+  return sources;
+}
+
+function customRegistryBinaryBaseURL(value) {
+  if (!value) {
+    return undefined;
+  }
+  let registry;
+  try {
+    registry = new URL(value);
+  } catch {
+    return undefined;
+  }
+  if (
+    registry.protocol !== "https:" ||
+    registry.username ||
+    registry.password ||
+    registry.origin === new URL(NPM_REGISTRY_URL).origin
+  ) {
+    return undefined;
+  }
+  return `${registry.href.replace(/\/$/, "")}/-/binary/viceme-cli`;
+}
+
+function parseDownloadBaseURL(value, allowInsecureURL) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error(`invalid binary download source ${value}`);
+  }
+  if (parsed.username || parsed.password) {
+    throw new Error("binary download sources must not contain credentials");
+  }
+  if (!allowInsecureURL && parsed.protocol !== "https:") {
+    throw new Error(`refusing non-HTTPS binary download source ${value}`);
+  }
+  if (allowInsecureURL && !["http:", "https:"].includes(parsed.protocol)) {
+    throw new Error(`unsupported binary download protocol ${parsed.protocol}`);
+  }
+  return parsed;
+}
+
+async function downloadVerifiedBinary({
+  asset,
+  expectedChecksum,
+  urls,
+  downloadImplementation,
+  allowInsecureURL,
+}) {
+  const failures = [];
+  for (const url of urls) {
+    try {
+      const downloaded = await downloadImplementation(url, { allowInsecureURL });
+      const binary = Buffer.isBuffer(downloaded) ? downloaded : Buffer.from(downloaded);
+      if (digest(binary) !== expectedChecksum) {
+        throw new Error(`checksum mismatch for ${asset}`);
+      }
+      return binary;
+    } catch (error) {
+      failures.push(`- ${url}: ${errorMessage(error)}`);
+    }
+  }
+  throw new Error(
+    `could not download a verified ${asset}; attempted:\n${failures.join("\n")}`,
+  );
+}
+
+async function downloadWithCurl(url, { allowInsecureURL = false } = {}) {
+  const parsed = parseDownloadBaseURL(url, allowInsecureURL);
+  const arguments_ = [
+    "--fail",
+    "--location",
+    "--silent",
+    "--show-error",
+    "--connect-timeout",
+    "10",
+    "--max-time",
+    "120",
+    "--max-redirs",
+    "5",
+  ];
+  if (!allowInsecureURL) {
+    arguments_.push("--proto", "=https", "--proto-redir", "=https");
+  }
+  arguments_.push(parsed.href);
+  return await new Promise((resolve, reject) => {
+    const child = spawn("curl", arguments_, {
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    const stdout = [];
+    let stderr = "";
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", (error) => {
+      if (error.code === "ENOENT") {
+        reject(new Error("curl is required to download the ViceMe CLI binary"));
+        return;
+      }
+      reject(error);
+    });
+    child.on("close", (code, signal) => {
+      if (code === 0) {
+        resolve(Buffer.concat(stdout));
+        return;
+      }
+      const reason = stderr.trim() || `curl exited ${code ?? `on signal ${signal}`}`;
+      reject(new Error(reason));
+    });
+  });
+}
+
 async function findValidGeneration(generationsDirectory, asset) {
   let entries;
   try {
@@ -170,22 +330,27 @@ async function cachedBinaryIsValid(binaryPath, checksumPath) {
   }
 }
 
-async function download(url, fetchImplementation, allowInsecureURL) {
-  const parsed = new URL(url);
-  if (!allowInsecureURL && parsed.protocol !== "https:") {
-    throw new Error(`refusing non-HTTPS release URL ${url}`);
-  }
-  const response = await fetchImplementation(url, {
-    redirect: "follow",
-    headers: { "user-agent": "@viceme-ai/cli npm launcher" },
-  });
-  if (!response.ok) {
-    throw new Error(`download failed (${response.status}) for ${url}`);
+function checksumForAsset(document, asset) {
+  let checksum;
+  for (const line of document.split(/\r?\n/)) {
+    if (line.trim() === "") {
+      continue;
+    }
+    const match = line.match(/^([a-fA-F0-9]{64})\s+([^\s]+)$/);
+    if (!match) {
+      throw new Error("bundled checksum document is invalid");
+    }
+    if (match[2] === asset) {
+      if (checksum) {
+        throw new Error(`bundled checksum document contains duplicate ${asset}`);
+      }
+      checksum = match[1].toLowerCase();
+    }
   }
-  if (!allowInsecureURL && response.url && new URL(response.url).protocol !== "https:") {
-    throw new Error(`release download redirected to a non-HTTPS URL`);
+  if (!checksum) {
+    throw new Error(`bundled checksum document does not contain ${asset}`);
   }
-  return Buffer.from(await response.arrayBuffer());
+  return checksum;
 }
 
 function parseChecksum(document) {
@@ -199,3 +364,7 @@ function parseChecksum(document) {
 function digest(buffer) {
   return createHash("sha256").update(buffer).digest("hex");
 }
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viceme-ai/cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Install and run the Viceme CLI and Viceme Agent Skill",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "npm/bin/",
     "npm/lib/",
+    "checksums.txt",
     "README.md",
     "README.zh.md",
     "CHANGELOG.md",