@yufengtadian/freedom-cli 1.13.2 → 1.14.0-preview

package/lib/shell.js

@@ -23,7 +23,9 @@ const {
   SHELL_EXE_NAME,
   localShellPath,
   nativePlatform,
+  normalizePlatform,
 } = require('./utils');
+const { applyWebkitTags } = require('./webkit');
 
 // GitHub Releases 下载源（可用环境变量覆盖）。
 // 资产命名约定：freedom-shell-<plat>（单文件二进制，不压缩）。
@@ -31,6 +33,17 @@ function releaseRepo() {
   return process.env.FREEDOM_SHELL_REPO || 'YUfeng12TA/freedom';
 }
 
+// 直连下载域与 API 域（测试可指向本地桩服务；默认走 GitHub）。
+function releaseBase() {
+  return (process.env.FREEDOM_SHELL_BASE || 'https://github.com').replace(/\/+$/, '');
+}
+function apiBase() {
+  return (process.env.FREEDOM_GITHUB_API || 'https://api.github.com').replace(/\/+$/, '');
+}
+function shellAssetName(plat) {
+  return `freedom-shell-${plat}`;
+}
+
 // 远程壳下载的默认版本：与当前包版本保持一致。
 // 通过环境变量 FREEDOM_SHELL_TAG 可强制覆盖；默认动态读取 package.json 的 version，
 // 避免与包版本漂移（历史曾硬编码 v1.1.10 导致下载到旧壳）。
@@ -46,7 +59,7 @@ function releaseTag() {
   return process.env.FREEDOM_SHELL_TAG || `v${pkgVersion()}`;
 }
 function releaseUrl(plat) {
-  return `https://github.com/${releaseRepo()}/releases/download/${releaseTag()}/freedom-shell-${plat}`;
+  return `${releaseBase()}/${releaseRepo()}/releases/download/${releaseTag()}/${shellAssetName(plat)}`;
 }
 
 // ---- 壳二进制平台格式校验 ----
@@ -163,6 +176,78 @@ function hasShell(plat) {
   return fs.existsSync(localShellPath(plat));
 }
 
+// ---- 发布代际预检（npm publish 前置门）----
+// 随包壳是三平台预编译二进制、不随 git 入库；改了框架源却忘了重新同步壳，就会发出
+// 「新 CLI + 旧壳」的混合代 tarball——FRDM3 断代下新 CLI 产的产物被旧壳直接拒跑
+// （1.14.0-preview 发布前实测：三只壳的生成时间全部早于当时 security.go 的改动时间）。
+// 判据取 mtime：壳文件的时间是「最后一次 download/build 同步」的证据，框架源比它新即可疑。
+// 盲区如实说明：全新克隆里壳刚下载完必然最新，此时本门只证明「同步之后没再改过源」。
+const PUBLISH_PLATFORMS = ['win-x64', 'darwin-arm64', 'linux-x64'];
+
+// newestSourceMtime 遍历将编进壳的框架源（*.go / go.mod / go.sum，排除 _test.go）。
+function newestSourceMtime(dir) {
+  let newest = 0;
+  let file = null;
+  const stack = [dir];
+  while (stack.length) {
+    const d = stack.pop();
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) {
+        stack.push(p);
+        continue;
+      }
+      if (!/\.(go|mod|sum)$/.test(e.name) || e.name.endsWith('_test.go')) continue;
+      const t = fs.statSync(p).mtimeMs;
+      if (t > newest) {
+        newest = t;
+        file = p;
+      }
+    }
+  }
+  return { newest, file };
+}
+
+function checkBundledShells(opts = {}) {
+  const plats = opts.platforms || PUBLISH_PLATFORMS;
+  const tplDir = opts.goTemplateDir || goTemplateDir();
+  const shellsDir = opts.shellsDir || shellDir();
+  const iso = (ms) => new Date(ms).toISOString();
+  const rel = (p, base) => path.relative(base, p).split(path.sep).join('/');
+  const problems = [];
+  const src = newestSourceMtime(tplDir);
+  if (!src.newest) problems.push(`预检无法判定代际：${tplDir} 下找不到 *.go 框架源`);
+  for (const plat of plats) {
+    const exe = path.join(shellsDir, plat, SHELL_EXE_NAME[plat] || 'freedom-shell');
+    if (!fs.existsSync(exe)) {
+      problems.push(`${plat}: 缺随包壳 ${rel(exe, shellsDir)}`);
+      continue;
+    }
+    const t = fs.statSync(exe).mtimeMs;
+    if (src.newest && t < src.newest) {
+      problems.push(`${plat}: 壳生成于 ${iso(t)}，早于框架源最新改动 ${iso(src.newest)}（${rel(src.file, tplDir)}）`);
+    }
+  }
+  return problems;
+}
+
+function preflightBundledShells(opts = {}) {
+  const problems = checkBundledShells(opts);
+  if (!problems.length) {
+    process.stdout.write('[freedom] 发布预检通过：随包壳不早于框架源\n');
+    return;
+  }
+  // 走 stderr + 退出码而非抛错：本函数由 npm 的 prepublishOnly 直接调用，抛错会带一串
+  // 对用户无用的堆栈，把「该重编哪几只壳」这句关键信息挤到屏幕外。
+  process.stderr.write(
+    'freedom: 随包壳与框架源代际不一致，禁止发布（发出即成混合代 tarball，新 CLI 的产物会被旧壳拒跑）：\n  - ' +
+      problems.join('\n  - ') +
+      '\n处置：先推 tag 让 CI 产壳，再 freedom shell download <plat> 覆盖 shell/<plat>' +
+      '（本机有工具链时 freedom shell build <plat>），然后重跑发布。\n'
+  );
+  process.exit(1);
+}
+
 // ---- 代理支持（修复：本地无 linux/mac 壳时自动下载必失败的历史根因） ----
 // 背景：GitHub Releases 资产重定向到 S3，Node 内置 fetch 直连在受限网络下
 // body 下载会卡死（可拿到 200 响应头但 arrayBuffer 永远不结束）。本机若跑
@@ -193,13 +278,14 @@ function hasCurl() {
 }
 
 // 用 curl 下载到 dest；成功返回 null，失败返回错误信息
-function curlDownload(url, dest, proxy) {
+function curlDownload(url, dest, proxy, extraHeaders) {
   const args = [
     '-L', '--fail', '--silent', '--show-error',
     '--connect-timeout', '20', '--max-time', '180', '--retry', '2',
     '--output', dest,
   ];
   if (proxy) args.push('--proxy', proxy);
+  for (const h of extraHeaders || []) args.push('-H', h);
   if (process.platform === 'win32' && /^https:/i.test(url)) {
     args.push('--ssl-no-revoke'); // 规避 Windows schannel CRYPT_E_REVOCATION_OFFLINE
   }
@@ -212,18 +298,124 @@ function curlDownload(url, dest, proxy) {
   return null;
 }
 
+// 平台参数收口：win / mac / linux 等别名归一到平台 key，识别不了给可读错误。
+function requirePlatform(plat) {
+  const key = normalizePlatform(plat);
+  if (!key) {
+    throw new Error(
+      `未知平台：${plat}。可选：${ALL_PLATFORMS.join(' / ')}` +
+        `（也接受 win / mac / linux 别名，可带架构后缀，如 mac-arm64）`
+    );
+  }
+  return key;
+}
+
+// 单次 HTTP GET 到 Buffer：配了代理就走 curl（原生支持 socks5），否则用内置 fetch。
+// API 端点需要 Accept 头，故 headers 显式传入。
+async function httpGetBuffer(url, headers) {
+  const proxy = resolveProxy();
+  if (proxy) {
+    if (!hasCurl()) throw new Error(`已配置代理 ${proxy} 但本机无 curl`);
+    const tmp = path.join(os.tmpdir(), `freedom-dl-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    const err = curlDownload(url, tmp, proxy, Object.entries(headers || {}).map(([k, v]) => `${k}: ${v}`));
+    try {
+      if (err) throw new Error(err);
+      return fs.readFileSync(tmp);
+    } finally {
+      try { fs.unlinkSync(tmp); } catch (e) { /* 清理失败忽略 */ }
+    }
+  }
+  const res = await fetch(url, {
+    headers: Object.assign({ 'User-Agent': 'freedom-cli' }, headers),
+    redirect: 'follow',
+    signal: AbortSignal.timeout(60000),
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+// 从 release 资产列表里挑出本平台的壳资产（需带 API url 字段）。
+function selectReleaseAsset(assets, plat) {
+  const name = shellAssetName(plat);
+  return (Array.isArray(assets) ? assets : []).find(
+    (a) => a && a.name === name && typeof a.url === 'string'
+  ) || null;
+}
+
+// 经 GitHub Release API 取壳：先按 tag 查 release 拿资产 id，再以 octet-stream 拉字节。
+// 背景（实测）：releases/download 会 302 到 S3 签名域，受限网络下响应头拿得到、
+// body 永远不结束；api.github.com 的资产端点由 GitHub 自己代理字节流，可稳定取回。
+async function downloadShellViaApi(plat) {
+  const token = process.env.FREEDOM_GITHUB_TOKEN || process.env.GITHUB_TOKEN;
+  const auth = token ? { Authorization: `Bearer ${token}` } : {};
+  const metaUrl = `${apiBase()}/repos/${releaseRepo()}/releases/tags/${releaseTag()}`;
+  let meta;
+  try {
+    meta = JSON.parse((await httpGetBuffer(metaUrl, Object.assign({ Accept: 'application/json' }, auth))).toString('utf8'));
+  } catch (e) {
+    throw new Error(`查询 release 元数据失败（${metaUrl}）：${e.message}`);
+  }
+  const asset = selectReleaseAsset(meta && meta.assets, plat);
+  if (!asset) {
+    throw new Error(`${releaseTag()} 中没有资产 ${shellAssetName(plat)}`);
+  }
+  return await httpGetBuffer(asset.url, Object.assign({ Accept: 'application/octet-stream' }, auth));
+}
+
 // 下载指定平台壳到包内 shell/<plat>/
 // 返回下载后的绝对路径；失败抛错。
+// 两条路径：直连 releases/download（有代理时经 curl）→ 失败回退 Release API 资产端点。
 async function downloadShell(plat) {
-  if (!ALL_PLATFORMS.includes(plat)) {
-    throw new Error(`未知平台：${plat}。可选：${ALL_PLATFORMS.join(' / ')}`);
-  }
+  plat = requirePlatform(plat);
   const url = releaseUrl(plat);
   const dest = localShellPath(plat);
   fs.mkdirSync(path.dirname(dest), { recursive: true });
 
+  let buf = null;
+  let primaryErr = null;
+  try {
+    buf = await fetchShellDirect(plat, url);
+  } catch (e) {
+    primaryErr = e;
+    process.stdout.write(
+      `[freedom] 直连下载壳 ${plat} 未完成（${String(e.message).split('\n')[0]}），回退 GitHub API 资产端点…\n`
+    );
+  }
+  if (!buf) {
+    try {
+      buf = await downloadShellViaApi(plat);
+    } catch (apiErr) {
+      throw new Error(
+        `下载壳 ${plat} 失败：直连与 Release API 两条路径都不通。\n` +
+          `  直连 ${url}：${primaryErr ? primaryErr.message : '未返回数据'}\n` +
+          `  API ${apiBase()}/repos/${releaseRepo()}：${apiErr.message}\n` +
+          `可设置代理重试（FREEDOM_SHELL_PROXY=socks5h://127.0.0.1:10808），` +
+          `或手动将壳二进制放入 ${dest}。`
+      );
+    }
+  }
+
+  // B13：下载后、落盘前校验格式/架构，防止代理劫持返回错误页或假壳被静默分发。
+  const fmt = detectShellFormat(buf);
+  const want = expectedFormat(plat);
+  if (fmt === 'unknown' || formatFamily(fmt) !== formatFamily(want)) {
+    throw new Error(
+      `下载的壳格式异常：期望 ${want}（${plat}），实际 detect=${fmt}。` +
+        `下载地址 ${url} 可能返回了错误页或非本平台假壳，请检查 GitHub Release 资产 ` +
+        `${releaseRepo()} 的 ${releaseTag()}。已放弃本次写入。`
+    );
+  }
+  fs.writeFileSync(dest, buf);
+  if (process.platform !== 'win32') {
+    fs.chmodSync(dest, 0o755);
+  }
+  return dest;
+}
+
+// 直连路径：代理在位时用 curl（原生支持 socks5/http 代理），否则用内置 fetch。
+// 返回内容 Buffer；网络失败、超时、非 2xx 一律抛错（由 downloadShell 决定回退）。
+async function fetchShellDirect(plat, url, dest) {
   const proxy = resolveProxy();
-  let buf;
   if (proxy) {
     process.stdout.write(`[freedom] 下载壳 ${plat}（经代理 ${proxy}）<- ${url}\n`);
     if (!hasCurl()) {
@@ -238,74 +430,49 @@ async function downloadShell(plat) {
       try { fs.unlinkSync(tmp); } catch (e) { /* 清理失败忽略 */ }
       throw new Error(
         `${curlErr}\n下载地址 ${url} 不可达。` +
-          `请确认代理 ${proxy} 可用（可执行 curl --proxy ${proxy} ${url} -I 自测），` +
-          `或手动将壳二进制放入 ${localShellPath(plat)}。`
+          `请确认代理 ${proxy} 可用（可执行 curl --proxy ${proxy} ${url} -I 自测）。`
       );
     }
     try {
-      buf = fs.readFileSync(tmp);
+      return fs.readFileSync(tmp);
     } finally {
       try { fs.unlinkSync(tmp); } catch (e) { /* 清理失败忽略 */ }
     }
-  } else {
-    process.stdout.write(`[freedom] 下载壳 ${plat} <- ${url}\n`);
-    let res;
-    try {
-      // 30s 超时：网络挂起时明确报错，避免构建进程无限阻塞
-      res = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(30000) });
-    } catch (e) {
-      if (e.name === 'AbortError' || e.name === 'TimeoutError') {
-        throw new Error(
-          `下载壳 ${plat} 超时（30s）。请检查网络后重试，` +
-            `或设置代理变量 FREEDOM_SHELL_PROXY=socks5h://127.0.0.1:10808 重试，` +
-            `或手动将壳二进制放入 ${localShellPath(plat)}。`
-        );
-      }
-      throw new Error(
-        `下载壳 ${plat} 失败：${e.message}。请检查网络（必要时设置 FREEDOM_SHELL_PROXY 走代理），` +
-          `或手动将壳二进制放入 ${localShellPath(plat)}。`
-      );
-    }
-    if (!res.ok) {
-      throw new Error(
-        `下载壳失败：HTTP ${res.status}。请确认 GitHub 仓库 ${releaseRepo()} 已发布 ` +
-          `${releaseTag()} 的资产 freedom-shell-${plat}，或手动将壳二进制放入 ${localShellPath(plat)}。`
-      );
-    }
-    buf = Buffer.from(await res.arrayBuffer());
   }
 
-  // B13：下载后、落盘前校验格式/架构，防止代理劫持返回错误页或假壳被静默分发。
-  const fmt = detectShellFormat(buf);
-  const want = expectedFormat(plat);
-  if (fmt === 'unknown' || formatFamily(fmt) !== formatFamily(want)) {
-    throw new Error(
-      `下载的壳格式异常：期望 ${want}（${plat}），实际 detect=${fmt}。` +
-        `下载地址 ${url} 可能返回了错误页或非本平台假壳，请检查 GitHub Release 资产 ` +
-        `${releaseRepo()} 的 ${releaseTag()}。已放弃本次写入。`
-    );
-  }
-  fs.writeFileSync(dest, buf);
-  if (process.platform !== 'win32') {
-    fs.chmodSync(dest, 0o755);
+  process.stdout.write(`[freedom] 下载壳 ${plat} <- ${url}\n`);
+  let res;
+  try {
+    // 30s 超时：网络挂起时明确报错，避免构建进程无限阻塞
+    res = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(30000) });
+  } catch (e) {
+    if (e.name === 'AbortError' || e.name === 'TimeoutError') {
+      throw new Error('下载超时（30s）');
+    }
+    throw new Error(`请求失败：${e.message}`);
   }
-  return dest;
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  if (!buf.length) throw new Error('响应体为空');
+  return buf;
 }
 
 // 本地用 Go 编译指定平台壳（需要 Go + 该平台编译环境）。
 // Windows 产物以 GUI 子系统编译（-H windowsgui），运行时无 cmd 黑窗。
-function buildShell(plat) {
-  if (!ALL_PLATFORMS.includes(plat)) {
-    throw new Error(`未知平台：${plat}。可选：${ALL_PLATFORMS.join(' / ')}`);
-  }
-  const res = spawnSync('go', ['version'], { encoding: 'utf8' });
-  if (res.error || res.status !== 0) {
-    throw new Error('未检测到 Go 工具链。请先安装 Go（https://go.dev/dl/），或改用 freedom shell download。');
-  }
-  const dest = localShellPath(plat);
-  fs.mkdirSync(path.dirname(dest), { recursive: true });
-
+//
+// opts.dest：产物落点（默认为包内通用壳位置）。high 模式传临时路径，编出的是
+// 本应用专属壳（Tier B），不得覆盖通用壳缓存。
+// opts.inject：{-X 符号路径: 值} 映射，用于把信任锚编进壳（见 lib/security.js shellInject）。
+// 值必须是命令行安全字符集——这里拼进单个 -ldflags 字符串，含空格即串味。
+// opts.stageGoFiles：{文件名: Go 源码} —— 编壳时**本次构建专属**的 Go 源文件（Tier B 的
+// keyslot 装配码），经 `go build -overlay` 虚拟进 pkg/freedom。刻意不落进 templates/go：
+// 那是随 npm 包分发的公共树，写进去一次就等于把某个产物的主密钥编进之后所有壳（含通用壳），
+// 还会撞上 CI 的 Template mirror 门。overlay 让它只活在这次构建的这一个进程里。
+function buildShell(plat, opts = {}) {
+  plat = requirePlatform(plat);
   // 本机只能编译本机平台（webview_go 依赖系统 WebView 框架，无法交叉编译）。
+  // 这道判断刻意前置于 Go 探测：平台不匹配是与工具有关的硬事实，先报工具有关
+  // 的错误会把「装个 Go 也没用」的场景误导成装 Go 能解决。
   // 统一走 utils.nativePlatform：Intel Mac 会明确抛"已不支持"，避免两套映射语义不一（B44）。
   const native = nativePlatform();
   if (plat !== native) {
@@ -314,23 +481,78 @@ function buildShell(plat) {
         `请在目标平台执行 freedom shell build ${plat}，或用 freedom shell download ${plat} 拉取 CI 预编译产物。`
     );
   }
+  const res = spawnSync('go', ['version'], { encoding: 'utf8' });
+  if (res.error || res.status !== 0) {
+    throw new Error(
+      '未检测到 Go 工具链。执行 freedom toolchain install go 自动安装（默认只打印命令，加 --apply 才执行），' +
+        '或手动获取 https://go.dev/dl/ ，或改用 freedom shell download 拉取预编译壳。'
+    );
+  }
+  const dest = opts.dest ? path.resolve(opts.dest) : localShellPath(plat);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
 
   const buildDir = goTemplateDir();
   // 剥离符号与调试信息（-s -w）+ 抹掉构建期绝对路径（-trimpath）：
   // 通用壳里编译进了 high 模式的密钥派生逻辑，函数名/DWARF 是给逆向者的地图。
   const ldflags = ['-s', '-w'];
+  for (const [sym, val] of Object.entries(opts.inject || {})) {
+    if (!/^[A-Za-z0-9_./:-]+$/.test(val)) {
+      throw new Error(`-X 注入值含非法字符（仅允许字母数字与 _./:-）：${sym}`);
+    }
+    ldflags.push('-X', `${sym}=${val}`);
+  }
   if (plat.startsWith('win')) ldflags.push('-H', 'windowsgui');
-  const build = spawnSync('go', ['build', '-trimpath', '-ldflags', ldflags.join(' '), '-o', dest, '.'], {
+  // Linux：新发行版只有 webkit2gtk-4.1，需要 -tags webkit2_41（探测与注入见 lib/webkit.js）。
+  const webkit = applyWebkitTags(process.env);
+  if (webkit.tags.length) {
+    process.stdout.write(`[freedom] 本机 WebKitGTK 仅有 4.1，构建加 -tags ${webkit.tags.join(',')}\n`);
+  }
+  // 本次构建专属的 Go 源文件经 overlay 虚拟进壳的包目录（见函数注释）。
+  const staged = stageOverlayFiles(buildDir, opts.stageGoFiles);
+  const args = ['build', '-trimpath'];
+  if (staged.overlayPath) args.push(`-overlay=${staged.overlayPath}`);
+  args.push('-ldflags', ldflags.join(' '), '-o', dest, '.');
+  const build = spawnSync('go', args, {
     cwd: buildDir,
     encoding: 'utf8',
-    env: { ...process.env, CGO_ENABLED: '1' },
+    env: Object.assign({ CGO_ENABLED: '1' }, webkit.env),
   });
-  if (build.error || build.status !== 0) {
-    throw new Error(`Go 编译失败：\n${build.stdout}\n${build.stderr}`);
+  try {
+    if (build.error || build.status !== 0) {
+      const hint = plat.startsWith('linux') && /webkit2gtk-4\.0/.test(`${build.stdout}${build.stderr}`)
+        ? `\n提示：本机未装 webkit2gtk-4.0/4.1 开发库。Ubuntu/Debian 执行 ` +
+          `sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev（老发行版用 4.0）后重试。`
+        : '';
+      throw new Error(`Go 编译失败：\n${build.stdout}\n${build.stderr}${hint}`);
+    }
+  } finally {
+    staged.cleanup();
   }
   return dest;
 }
 
+// stageOverlayFiles 把 {文件名: 源码} 写成临时文件并产出一份 go command 认的 overlay 清单
+// （Replace: 虚拟路径 → 真实路径）。返回 { overlayPath, cleanup }；无文件时 overlayPath 为 null。
+// 虚拟路径必须落在目标包目录下，否则不会被视为该包的源文件。
+function stageOverlayFiles(buildDir, files) {
+  const entries = Object.entries(files || {});
+  if (!entries.length) return { overlayPath: null, cleanup() {} };
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'freedom-stage-'));
+  const replace = {};
+  for (const [name, src] of entries) {
+    if (!/^keyslot_[0-9a-f]{6}\.go$/.test(name)) {
+      fs.rmSync(dir, { recursive: true, force: true });
+      throw new Error(`internal: 不接受的壳源文件名 ${name}（只允许 keyslot_<tag>.go）`);
+    }
+    const real = path.join(dir, name);
+    fs.writeFileSync(real, src, 'utf8');
+    replace[path.join(buildDir, 'pkg', 'freedom', name)] = real;
+  }
+  const overlayPath = path.join(dir, 'overlay.json');
+  fs.writeFileSync(overlayPath, JSON.stringify({ Replace: replace }), 'utf8');
+  return { overlayPath, cleanup: () => fs.rmSync(dir, { recursive: true, force: true }) };
+}
+
 function nativePlatformKey() {
   // 已废弃：统一使用 utils.nativePlatform（B44），本函数保留仅作内部兜底，勿再调用。
   return nativePlatform();
@@ -346,4 +568,6 @@ module.exports = {
   detectShellFormat,
   expectedFormat,
   validateLocalShell,
+  checkBundledShells,
+  preflightBundledShells,
 };