@yufengtadian/freedom-cli 1.12.15 → 1.12.16

package/README.md

@@ -4,6 +4,11 @@ Freedom 桌面壳打包工具：把你的 Web 前端一键打包成跨平台桌
 
 基于自研 Freedom WebView 壳层（对标 Wails / Tauri）：前端完全自由、后端可任意语言、渲染复用系统 WebView（Windows WebView2 / macOS WKWebView / Linux WebKitGTK），产物为单个可执行文件 + resources 目录，前端页面内存加载，不占本地端口。
 
+**v1.12.16 自动更新 + 完整 CLI 模式 + 壳生命周期全面防御**：
+- **自动检测版本并自动更新**：`freedom update` / `freedom check-update` 检测到新版本即自动执行 `npm install -g @yufengtadian/freedom-cli@latest` 升级，**不再需要手动执行 npm 命令**；每次命令执行成功后静默自检，发现新版自动更新（6 小时频控防骚扰，非全局安装给出明确升级指引）；TUI 主菜单「检查 / 自动更新」同步接入；
+- **完整 CLI 模式**：无参数运行 `freedom` 直接进入交互式完整 CLI（打包 / 新建项目 / 配置 / 壳管理 / 教程 / 自动更新 / 退出）；管道与脚本环境自动降级打印帮助，不卡死；
+- **壳生命周期全面防御（B51-B58 闭环）**：webview 全方法销毁防护、user32 proc 去重、WebView2 缺失可操作提示；`webview_create` 失败（如缺 WebKitGTK）返回 nil 后新壳走明确失败提示而非空指针崩溃；用户 `Bind` 的方法不再被 config.json 进程后端静默覆盖失效；help 文案与自动更新实现对齐，清理死代码。
+
 **v1.12.15 补发壳生命周期稳定性修复**：v1.12.14 的 npm 上架时间早于修复提交，上架版预编译壳未包含悬垂指针修复（窗口操作 / 代理端口触发随机退出的根因）；本版正式把含 B50 修复的预编译壳随 npm 包分发——
 - 壳销毁生命周期修复：`webview.Destroy()` 后经 Emit / Quit / WindowHandle / binding 回调访问已释放 C 对象（悬垂指针）导致随机退出；新增 `destroyed` 原子标记，Dispatch / Eval / binding 回调销毁后一律跳过原生调用，`Run` 在 `Destroy` 前清空 `App.view`，事件与绑定回调加 `recover` 兜底；
 - 使用全局包构建的下游应用（如 DSH）升级到本版后，随机退出问题一并消除（可用二进制字符串指纹 `freedom: binding panic` 核对）。

package/bin/freedom.js

@@ -2,11 +2,21 @@
 'use strict';
 
 const { run } = require('../lib/cli');
-const { maybeNotifyUpdate } = require('../lib/update');
+const { maybeAutoUpdate, formatUpdateResult } = require('../lib/update');
+const theme = require('../lib/theme');
+
+const cmd = process.argv[2];
+// TUI（无参 / freedom tui）与显式更新命令内部已处理更新，bin 层不再重复触发
+const handled = cmd === undefined || cmd === 'tui' || cmd === 'update' || cmd === 'check-update';
 
 run(process.argv.slice(2)).then(async (code) => {
-  if (code === 0 && process.argv[2] !== 'tui') {
-    try { await maybeNotifyUpdate(); } catch (e) { /* 检测失败静默 */ }
+  // 命令成功且非 TUI / 非显式更新命令时，静默执行自动更新（检测到新版本自动升级，无需用户手动操作）
+  if (code === 0 && !handled) {
+    try {
+      const res = await maybeAutoUpdate();
+      const notice = formatUpdateResult(res, theme);
+      if (notice.length) console.log(notice.join('\n'));
+    } catch (e) { /* 更新流程失败静默 */ }
   }
   // 用 exitCode 让 Node 自然刷新 stdout 后退出，避免 process.exit 截断管道输出（历史 bug B28）
   process.exitCode = code || 0;

package/lib/cli.js

@@ -19,7 +19,8 @@ function help() {
   L.push(`  ${paint('用法：', C.bold, C.fg.white)} ${paint('freedom <command> [options]', C.fg.cyan, C.bold)}`);
   L.push('');
   L.push(section('交互式界面'));
-  L.push(`  ${paint('freedom tui', C.fg.cyan, C.bold)}              ${dim('进入交互式 TUI（新建 / 打包 / 配置 / 壳管理）')}`);
+  L.push(`  ${paint('freedom', C.fg.cyan, C.bold)}                  ${dim('进入完整 CLI 模式（交互式菜单，新建 / 打包 / 配置 / 壳管理）')}`);
+  L.push(`  ${paint('freedom tui', C.fg.cyan, C.bold)}              ${dim('同上（兼容写法，显式进入交互式模式）')}`);
   L.push(section('项目'));
   L.push(`  ${paint('freedom init [目录] [--force]', C.fg.cyan)}    ${dim('在当前 / 指定目录新建项目模板')}`);
   L.push(`  ${paint('freedom tutorial', C.fg.cyan)}                 ${dim('再次打开安装教程')}`);
@@ -41,7 +42,7 @@ function help() {
   L.push(`  ${paint('freedom config set <key> <value>', C.fg.cyan)} ${dim('修改单个配置项')}`);
   L.push(section('版本'));
   L.push(`  ${paint('freedom version', C.fg.cyan)}             ${dim('显示版本并检测最新版本')}`);
-  L.push(`  ${paint('freedom update', C.fg.cyan)}              ${dim('检查新版本并给出升级命令')}`);
+  L.push(`  ${paint('freedom update', C.fg.cyan)}              ${dim('检查新版本并立即自动更新')}`);
   L.push(`  ${paint('freedom help', C.fg.cyan)}                ${dim('显示本帮助')}`);
   L.push('');
   L.push(section('平台'));
@@ -63,7 +64,15 @@ async function run(argv) {
   const [cmd, ...rest] = argv;
 
   switch (cmd) {
-    case undefined:
+    case undefined: {
+      // 无参数：交互式终端进入完整 CLI 模式（TUI）；管道 / 脚本环境打印帮助，避免卡死
+      if (process.stdin.isTTY && process.stdout.isTTY) {
+        return await require('./tui').tui(process.cwd());
+      }
+      console.log(help());
+      return 0;
+    }
+
     case 'help':
     case '--help':
     case '-h':
@@ -76,7 +85,7 @@ async function run(argv) {
       const r = await update.checkUpdate({ force: true });
       console.log(versionCard(r.current, r.latest, r.hasUpdate));
       if (r.hasUpdate && r.latest) {
-        console.log(`  ${tip('升级命令：')}${paint(`npm install -g ${update.PKG_NAME}@latest`, C.fg.cyan, C.bold)}`);
+        console.log(`  ${tip('检测到新版本，将自动更新。')}`);
         console.log('');
       }
       return 0;
@@ -86,14 +95,15 @@ async function run(argv) {
     case 'check-update': {
       const r = await update.checkUpdate({ force: true });
       console.log(versionCard(r.current, r.latest, r.hasUpdate));
-      if (r.hasUpdate && r.latest) {
-        console.log(`  ${tip('检测到新版本，执行以下命令升级：')}`);
-        console.log(`    ${paint(`npm install -g ${update.PKG_NAME}@latest`, C.fg.cyan, C.bold)}`);
-        console.log('');
-      } else if (r.latest) {
+      if (r.latest && !r.hasUpdate) {
         console.log(`  ${ok('当前已是最新版本。')}`);
-      } else {
+      } else if (!r.latest) {
         console.log(`  ${warn('检查失败：网络不可用或 npm registry 未响应，请稍后重试。')}`);
+      } else {
+        // 有新版：立即自动更新（freedom update = 强制更新，无需手动执行 npm 命令）
+        const res = await update.maybeAutoUpdate({ force: true, r });
+        const notice = update.formatUpdateResult(res, theme);
+        if (notice.length) console.log(notice.join('\n'));
       }
       return 0;
     }

package/lib/tui.js

@@ -213,7 +213,8 @@ async function buildFlow(tui, cwd) {
   // 平台多选：默认勾选当前平台
   const native = require('./utils').nativePlatform();
   const checked = [ALL_PLATFORMS.indexOf(native)];
-  const picked = await tui.multiselect('选择目标平台（多选）', ALL_PLATFORMS, { checked });
+  // linux-arm64 无 CI 预编译资产：全选时按 all（win-x64/darwin-arm64/linux-x64）处理，避免 404 拖垮构建（见 utils.DIST_PLATFORMS）
+  const picked = await tui.multiselect('选择目标平台（多选；linux-arm64 无预编译资产，全选仅含三平台）', ALL_PLATFORMS, { checked });
   if (picked === null) return;
   const platforms = picked.map((i) => ALL_PLATFORMS[i]);
   const platArg = picked.length === ALL_PLATFORMS.length ? 'all' : platforms.join(',');
@@ -303,20 +304,36 @@ async function tutorialFlow(tui) {
 }
 
 async function updateFlow(tui) {
-  const { checkUpdate, PKG_NAME } = require('./update');
-  const r = await checkUpdate({ force: true });
-  const lines = [
-    { text: C.fgWhite + C.bold + `  当前版本：v${r.current}` + C.reset },
-  ];
-  if (r.latest) {
-    lines.push({ text: C.fgCyan + `  最新版本：v${r.latest}` + C.reset });
-    lines.push({ text: r.hasUpdate
-      ? C.fgYellow + `  发现新版本，可执行：npm install -g ${PKG_NAME}@latest` + C.reset
-      : C.fgGreen + `  已是最新版本` + C.reset });
+  const update = require('./update');
+  const r = await update.checkUpdate({ force: true });
+  const rows = [{ text: C.fgWhite + C.bold + `  当前版本：v${r.current}` + C.reset }];
+  if (!r.latest) {
+    rows.push({ text: C.fgGray + `  检查失败：网络不可用，请稍后重试` + C.reset });
+    return tui.message('检查 / 自动更新', rows);
+  }
+  rows.push({ text: C.fgCyan + `  最新版本：v${r.latest}` + C.reset });
+  if (!r.hasUpdate) {
+    rows.push({ text: C.fgGreen + `  已是最新版本` + C.reset });
+    return tui.message('检查 / 自动更新', rows);
+  }
+  // 有新版本：直接自动更新（无需用户手动执行 npm 命令）
+  let res = null;
+  await tui.runTask(async () => {
+    res = await update.maybeAutoUpdate({ force: true, r });
+  });
+  if (res && res.updated) {
+    rows.push({ text: C.fgGreen + `  ✓ 已自动更新到 v${res.to}（原 v${res.from}）` + C.reset });
+    rows.push({ text: C.fgGray + `  重启本 TUI 后即为新版本` + C.reset });
+  } else if (res && res.notGlobal) {
+    rows.push({ text: C.fgYellow + `  ⚠ 检测到新版本，当前为非全局安装，请手动执行：npm install -g ${update.pkgName()}@latest` + C.reset });
+  } else if (res && res.failed) {
+    rows.push({ text: C.fgYellow + `  ⚠ 自动更新失败：${res.detail || '未知原因'}` + C.reset });
+  } else if (res && res.throttled) {
+    rows.push({ text: C.fgYellow + `  ⚠ 自动更新 6h 内已尝试过，本次跳过` + C.reset });
   } else {
-    lines.push({ text: C.fgGray + `  检查失败：网络不可用，请稍后重试` + C.reset });
+    rows.push({ text: C.fgGray + `  自动更新流程已结束` + C.reset });
   }
-  await tui.message('检查版本更新', lines);
+  await tui.message('检查 / 自动更新', rows);
 }
 
 function coerce(value) {
@@ -336,7 +353,7 @@ async function tui(cwd) {
   app.enter();
   let keep = true;
   while (keep) {
-    const items = ['打包桌面应用', '新建项目', '修改配置', '壳管理', '打开教程', '检查更新', '退出'];
+    const items = ['打包桌面应用', '新建项目', '修改配置', '壳管理', '打开教程', '检查 / 自动更新', '退出'];
     const idx = await app.menu('主菜单', items, {
       footer: `工作目录：${cwd}   ↑ ↓ 选择 · Enter 确认 · q 退出`,
     });

package/lib/update.js

@@ -1,21 +1,42 @@
 'use strict';
 
-// 版本检测：零依赖（https 内置），查询 npm registry 最新版本并对比本地版本。
-// - 结果缓存到 ~/.freedom/update-cache.json，24h 内不重复联网（离线不打扰）
-// - compareVersions 手写 semver 比较（仅处理 x.y.z 数字前缀，满足语义版本场景）
-// - 所有联网失败均静默降级，绝不阻塞主流程
+// 版本检测与自动更新：零依赖（https 内置）
+//
+// 版本检测：
+//   - 查询 npm registry 最新版本并对比本地版本，结果缓存 24h（离线不打扰）
+// 自动更新：
+//   - 检测到新版本时自动执行 `npm install -g <pkg>@latest`，无需用户手动升级
+//   - 仅当当前包为 npm 全局安装时自动更新（npm link / 本地目录安装仅提示手动命令）
+//   - 自动更新带 6h 频控（FREEDOM_AUTO_UPDATE_FORCE=1 可强制），失败静默降级不阻塞主流程
+// 开关：
+//   - FREEDOM_AUTO_UPDATE=0 / false / off 可关闭自动更新（仅保留版本提示）
+// 所有联网 / 更新失败均静默降级，绝不阻塞主流程。
+// compareVersions 手写 semver 比较（仅处理 x.y.z 数字前缀，满足语义版本场景）。
 
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const https = require('https');
+const { spawn, execFileSync } = require('child_process');
 const { packageRoot } = require('./utils');
 
 const PKG_NAME = '@yufengtadian/freedom-cli';
 const REGISTRY = `https://registry.npmjs.org/${encodeURIComponent(PKG_NAME)}/latest`;
 const CACHE_FILE = path.join(os.homedir(), '.freedom', 'update-cache.json');
-const CACHE_TTL = 24 * 60 * 60 * 1000; // 24 小时
+const CACHE_TTL = 24 * 60 * 60 * 1000; // 版本检测缓存 24h
+const AUTO_UPDATE_GAP = 6 * 60 * 60 * 1000; // 自动更新尝试频控 6h
 const REQUEST_TIMEOUT = 4000;
+const UPDATE_TIMEOUT = 120000; // npm install 超时 120s
+
+// 实际安装的包名：优先读 package.json（fork / 改名时自动跟随），兜底 PKG_NAME
+function pkgName() {
+  try {
+    const pkg = require(path.join(packageRoot(), 'package.json'));
+    return typeof pkg.name === 'string' && pkg.name ? pkg.name : PKG_NAME;
+  } catch (e) {
+    return PKG_NAME;
+  }
+}
 
 function currentVersion() {
   return require(path.join(packageRoot(), 'package.json')).version;
@@ -34,11 +55,22 @@ function compareVersions(a, b) {
   return 0;
 }
 
-function readCache() {
+// ---- 缓存 ----
+
+// 读取原始缓存（不校验 TTL），供自动更新频控使用；损坏返回 null
+function readRawCache() {
   try {
     const j = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
-    if (j && j.latest && Date.now() - j.ts < CACHE_TTL) return j;
-  } catch (e) { /* 无缓存或损坏，忽略 */ }
+    return j && typeof j === 'object' ? j : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+// 读取有效缓存：latest 存在且未过期才返回（版本检测用）
+function readCache() {
+  const j = readRawCache();
+  if (j && j.latest && Date.now() - j.ts < CACHE_TTL) return j;
   return null;
 }
 
@@ -49,30 +81,38 @@ function writeCache(data) {
   } catch (e) { /* 写缓存失败静默 */ }
 }
 
-// 从 npm registry 拉取 latest 版本；失败 / 超时返回 null
+function clearCache() {
+  try { fs.unlinkSync(CACHE_FILE); } catch (e) { /* 忽略 */ }
+}
+
+// ---- 联网检测 ----
+// 从 npm registry 拉取 latest 版本；失败 / 超时返回 null。
+// B54：timeout 时显式 settle，避免 https 请求超时后 Promise 永不 resolve（悬空）。
 function fetchLatest(timeout = REQUEST_TIMEOUT) {
   return new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => { if (!settled) { settled = true; resolve(v); } };
     const req = https.get(REGISTRY, {
       headers: { 'user-agent': 'freedom-cli', accept: 'application/json' },
       timeout,
     }, (res) => {
       if (res.statusCode !== 200) {
         res.resume();
-        return resolve(null);
+        return done(null);
       }
       let body = '';
       res.setEncoding('utf8');
       res.on('data', (chunk) => { body += chunk; });
       res.on('end', () => {
         try {
-          resolve(JSON.parse(body).version || null);
+          done(JSON.parse(body).version || null);
         } catch (e) {
-          resolve(null);
+          done(null);
         }
       });
     });
-    req.on('timeout', () => req.destroy());
-    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); done(null); });
+    req.on('error', () => done(null));
   });
 }
 
@@ -89,21 +129,131 @@ async function checkUpdate({ force = false } = {}) {
   return { current, latest, hasUpdate };
 }
 
-// 静默异步通知：仅在检测到新版本时打印一行升级提示，不阻塞调用方
-async function maybeNotifyUpdate() {
+// ---- 全局安装判定 ----
+
+function npmGlobalRoot() {
   try {
-    const r = await checkUpdate();
-    if (r.hasUpdate && r.latest) {
-      const theme = require('./theme');
-      console.log('');
-      console.log(`  ${theme.paint('➜', theme.C.fg.magenta, theme.C.bold)} ${theme.paint(`新版本可用 ${r.latest}（当前 ${r.current}）`, theme.C.fg.yellow)}`);
-      console.log(`    ${theme.dim('运行')} ${theme.paint(`npm install -g ${PKG_NAME}@latest`, theme.C.fg.cyan)} ${theme.dim('升级，或')} ${theme.paint('freedom update', theme.C.fg.cyan)} ${theme.dim('查看详情')}`);
-      console.log('');
-    }
-  } catch (e) { /* 检测失败静默 */ }
+    const cmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const out = execFileSync(cmd, ['root', '-g'], {
+      encoding: 'utf8',
+      timeout: 10000,
+      windowsHide: true,
+      shell: process.platform === 'win32',
+    });
+    return out.trim() || null;
+  } catch (e) {
+    return null;
+  }
+}
+
+// target 是否位于 root 目录内（含直接子级）；任一为空返回 false
+function isPathInside(root, target) {
+  if (!root || !target) return false;
+  const rel = path.relative(root, target);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+// 当前安装是否为 npm 全局安装。
+// 仅全局安装才允许自动更新；npm link / 本地目录安装时仅提示手动命令，
+// 避免自动安装出一份与当前工作副本无关的全局副本（行为不可预期）。
+function isGlobalInstall() {
+  const root = npmGlobalRoot();
+  if (!root) return false;
+  return isPathInside(root, packageRoot());
+}
+
+// ---- 自动更新执行 ----
+
+// 执行 `npm install -g <pkg>@<latest>`；返回 { ok, detail }
+function performAutoUpdate(latest, { timeoutMs = UPDATE_TIMEOUT } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => { if (!settled) { settled = true; resolve(v); } };
+    const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const child = spawn(
+      npm,
+      ['install', '-g', `${pkgName()}@${latest}`, '--no-audit', '--no-fund', '--loglevel=error'],
+      { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, shell: process.platform === 'win32' }
+    );
+    let out = '';
+    let err = '';
+    child.stdout.on('data', (d) => { out += d; });
+    child.stderr.on('data', (d) => { err += d; });
+    const timer = setTimeout(() => {
+      try { child.kill(); } catch (e) { /* ignore */ }
+      done({ ok: false, detail: `更新超时（${Math.round(timeoutMs / 1000)}s）` });
+    }, timeoutMs);
+    child.on('error', (e) => { clearTimeout(timer); done({ ok: false, detail: e.message }); });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (code === 0) done({ ok: true, detail: (out.trim() || err.trim() || '') });
+      else done({ ok: false, detail: (err.trim() || out.trim() || `npm 退出码 ${code}`) });
+    });
+  });
+}
+
+// 自动更新频控是否到期：距上次尝试超过 AUTO_UPDATE_GAP 才算到期
+function autoUpdateDue(now = Date.now()) {
+  const raw = readRawCache();
+  if (!raw || !raw.lastAutoAttempt) return true;
+  return now - raw.lastAutoAttempt >= AUTO_UPDATE_GAP;
+}
+
+// 自动更新完整流程。返回结构化结果供调用方打印。
+// r：可传入预取的 checkUpdate 结果，避免重复联网；force：跳过缓存与频控。
+async function maybeAutoUpdate({ force = false, r = null } = {}) {
+  // 开关：FREEDOM_AUTO_UPDATE=0 / false / off 关闭自动更新
+  const flag = (process.env.FREEDOM_AUTO_UPDATE || '').toLowerCase();
+  if (flag === '0' || flag === 'false' || flag === 'off') return { skipped: 'disabled' };
+
+  const info = r || (await checkUpdate({ force }));
+  if (!info.latest) return { offline: true };
+  if (!info.hasUpdate) return { upToDate: true, latest: info.latest };
+  if (!isGlobalInstall()) {
+    return { notGlobal: true, latest: info.latest, current: info.current };
+  }
+
+  const forceFlag = (process.env.FREEDOM_AUTO_UPDATE_FORCE || '').toLowerCase();
+  const skipThrottle = force || forceFlag === '1' || forceFlag === 'true';
+  if (!skipThrottle && !autoUpdateDue()) {
+    return { throttled: true, latest: info.latest, current: info.current };
+  }
+
+  // 先标记尝试再执行，防止多进程并发 / 失败后风暴重试
+  writeCache({ latest: info.latest, lastAutoAttempt: Date.now() });
+  const res = await performAutoUpdate(info.latest);
+  if (res.ok) {
+    clearCache(); // 更新成功后清缓存，下次以新版本为基准重新检测
+    return { updated: true, from: info.current, to: info.latest, detail: res.detail };
+  }
+  return { failed: true, latest: info.latest, current: info.current, detail: res.detail };
+}
+
+// 把自动更新结果渲染为终端提示行（供 CLI 打印；TUI 自行拼装）。
+// upToDate / offline / skipped 不产生提示（静默），返回空数组。
+function formatUpdateResult(res, theme) {
+  const { paint, C, ok, warn, tip, dim } = theme;
+  const lines = [];
+  if (res.updated) {
+    lines.push(`  ${ok(`已自动更新到 v${res.to}（原 v${res.from}）。`)}`);
+    lines.push(`    ${dim('下次运行')} ${paint('freedom', C.fg.cyan)} ${dim('即为新版本。')}`);
+  } else if (res.notGlobal) {
+    lines.push(`  ${warn(`检测到新版本 v${res.latest}（当前 v${res.current}）。`)}`);
+    lines.push(`    ${dim('当前为非全局安装，无法自动更新，请手动执行：')}${paint(`npm install -g ${pkgName()}@latest`, C.fg.cyan, C.bold)}`);
+  } else if (res.failed) {
+    lines.push(`  ${warn('自动更新失败：')}${dim(res.detail || '未知原因')}`);
+    lines.push(`    ${dim('可稍后运行')} ${paint('freedom update', C.fg.cyan)} ${dim('重试，或手动执行：')}${paint(`npm install -g ${pkgName()}@latest`, C.fg.cyan, C.bold)}`);
+  } else if (res.throttled) {
+    lines.push(`  ${tip(`新版本 v${res.latest} 存在，6h 内已尝试过自动更新，本次跳过。`)}`);
+    lines.push(`    ${dim('运行')} ${paint('freedom update', C.fg.cyan)} ${dim('可立即强制更新。')}`);
+  }
+  return lines;
 }
 
 module.exports = {
-  PKG_NAME, REGISTRY, CACHE_FILE, CACHE_TTL,
-  currentVersion, compareVersions, checkUpdate, maybeNotifyUpdate,
+  PKG_NAME, REGISTRY, CACHE_FILE, CACHE_TTL, AUTO_UPDATE_GAP,
+  pkgName, currentVersion, compareVersions, checkUpdate,
+  readRawCache, readCache, writeCache, clearCache,
+  npmGlobalRoot, isPathInside, isGlobalInstall,
+  performAutoUpdate, autoUpdateDue, maybeAutoUpdate, formatUpdateResult,
 };

package/package.json

@@ -1,39 +1,39 @@
-{
-  "name": "@yufengtadian/freedom-cli",
-  "version": "1.12.15",
-  "description": "Freedom WebView desktop shell packaging tool - no Go toolchain required, one command packs three-platform desktop apps",
-  "keywords": [
-    "desktop",
-    "webview",
-    "electron-alternative",
-    "wails",
-    "tauri",
-    "frontend",
-    "cross-platform"
-  ],
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "freedom": "bin/freedom.js"
-  },
-  "files": [
-    "bin",
-    "lib",
-    "shell",
-    "templates",
-    "tutorial",
-    "postinstall.js",
-    "README.md"
-  ],
-  "scripts": {
-    "postinstall": "node postinstall.js"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "rcedit": "^4.0.1"
-  }
-}
+{
+  "name": "@yufengtadian/freedom-cli",
+  "version": "1.12.16",
+  "description": "Freedom WebView desktop shell packaging tool - no Go toolchain required, one command packs three-platform desktop apps",
+  "keywords": [
+    "desktop",
+    "webview",
+    "electron-alternative",
+    "wails",
+    "tauri",
+    "frontend",
+    "cross-platform"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "freedom": "bin/freedom.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "shell",
+    "templates",
+    "tutorial",
+    "postinstall.js",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node postinstall.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "rcedit": "^4.0.1"
+  }
+}

package/templates/go/pkg/freedom/center_windows.go

@@ -3,18 +3,9 @@
 package freedom
 
 import (
-	"syscall"
 	"unsafe"
 )
 
-var (
-	user32            = syscall.NewLazyDLL("user32.dll")
-	getSystemMetrics  = user32.NewProc("GetSystemMetrics")
-	moveWindow        = user32.NewProc("MoveWindow")
-	monitorFromWindow = user32.NewProc("MonitorFromWindow")
-	getMonitorInfo    = user32.NewProc("GetMonitorInfoW")
-)
-
 const (
 	smCxScreen           = 16
 	smCyScreen           = 17
@@ -38,19 +29,22 @@ type monitorInfo struct {
 // webview_go 未提供 SetPosition，这里通过原生 HWND + MoveWindow 定位。
 // 优先居中到窗口当前所在监视器的工作区（rcWork）：多屏副屏（负坐标 /
 // 不同分辨率 / 任务栏遮挡）下也能正确居中；API 失败时回退主屏全屏居中。
+//
+// user32 过程句柄（procGetSystemMetrics / procMoveWindow / procMonitorFromWindow /
+// procGetMonitorInfo）统一声明在 window_windows.go，避免两套重复 NewProc。
 func (a *App) applyCenter() {
-	if !a.cfg.Center || a.view == nil {
+	if !a.cfg.Center {
 		return
 	}
-	hwnd := uintptr(unsafe.Pointer(a.view.Window()))
+	hwnd := a.WindowHandle()
 	if hwnd == 0 {
 		return
 	}
-	mon, _, _ := monitorFromWindow.Call(hwnd, monitorDefaultToNear)
+	mon, _, _ := procMonitorFromWindow.Call(hwnd, monitorDefaultToNear)
 	if mon != 0 {
 		var mi monitorInfo
 		mi.cbSize = uint32(unsafe.Sizeof(mi))
-		if r1, _, _ := getMonitorInfo.Call(mon, uintptr(unsafe.Pointer(&mi))); r1 != 0 {
+		if r1, _, _ := procGetMonitorInfo.Call(mon, uintptr(unsafe.Pointer(&mi))); r1 != 0 {
 			work := mi.rcWork
 			sw := work.right - work.left
 			sh := work.bottom - work.top
@@ -62,13 +56,13 @@ func (a *App) applyCenter() {
 			if y < 0 {
 				y = 0
 			}
-			moveWindow.Call(hwnd, uintptr(x), uintptr(y), uintptr(a.cfg.Width), uintptr(a.cfg.Height), 1)
+			procMoveWindow.Call(hwnd, uintptr(x), uintptr(y), uintptr(a.cfg.Width), uintptr(a.cfg.Height), 1)
 			return
 		}
 	}
 	// 回退：主屏全屏尺寸居中（原实现）
-	sw, _, _ := getSystemMetrics.Call(smCxScreen)
-	sh, _, _ := getSystemMetrics.Call(smCyScreen)
+	sw, _, _ := procGetSystemMetrics.Call(smCxScreen)
+	sh, _, _ := procGetSystemMetrics.Call(smCyScreen)
 	x := int(sw/2) - a.cfg.Width/2
 	y := int(sh/2) - a.cfg.Height/2
 	if x < 0 {
@@ -77,5 +71,5 @@ func (a *App) applyCenter() {
 	if y < 0 {
 		y = 0
 	}
-	moveWindow.Call(hwnd, uintptr(x), uintptr(y), uintptr(a.cfg.Width), uintptr(a.cfg.Height), 1)
+	procMoveWindow.Call(hwnd, uintptr(x), uintptr(y), uintptr(a.cfg.Width), uintptr(a.cfg.Height), 1)
 }

package/templates/go/pkg/freedom/freedom.go

@@ -110,7 +110,14 @@ func (a *App) Bind(name string, fn interface{}) error {
 	if !ok {
 		return fmt.Errorf("freedom: Bind 仅适用于内嵌 Go 后端；当前后端为 %T，方法请在进程后端中注册", a.backend)
 	}
-	return eb.Bind(name, fn)
+	if err := eb.Bind(name, fn); err != nil {
+		return err
+	}
+	// B56：用户显式绑定方法 = 显式指定内嵌后端。置位后外部 resources/config.json
+	// 的 backend 配置不再覆盖（loadRuntimeConfig 仅当 !backendExplicit 时生效），
+	// 避免"用户 Bind 的方法被 config.json 的进程后端静默替换而全部失效"。
+	a.backendExplicit = true
+	return nil
 }
 
 // Unbind 移除先前 Bind 的方法（内嵌后端）。
@@ -152,7 +159,11 @@ func (a *App) Run() {
 
 	w := webview.New(a.cfg.Debug)
 	if w == nil {
-		fmt.Println("freedom: failed to create webview")
+		if !webview2Available() {
+			fmt.Println("freedom: failed to create webview: 未检测到 WebView2 Runtime，请安装 Microsoft Edge WebView2 Runtime（https://go.microsoft.com/fwlink/?linkid=2124703）后重试")
+		} else {
+			fmt.Println("freedom: failed to create webview")
+		}
 		return
 	}
 	a.setView(w)

package/templates/go/pkg/freedom/window_other.go

@@ -24,6 +24,10 @@ func (a *App) applyTitleBar() {
 // setWindowIcon 在 macOS / Linux 上为空实现（图标由应用包 / 窗口管理器决定）。
 func (a *App) setWindowIcon() {}
 
+// webview2Available 非 Windows 平台恒返回 true（macOS WKWebView / Linux WebKitGTK，
+// 不依赖 WebView2 Runtime）。
+func webview2Available() bool { return true }
+
 // windowControl 处理前端 window.freedom.window.* 请求（macOS / Linux 实现）。
 //
 // 窗口控制类动作（最小化/最大化/还原/关闭/查询）直接转发到 webview 层的原生

package/templates/go/pkg/freedom/window_windows.go

@@ -13,6 +13,7 @@ import (
 	"syscall"
 
 	"golang.org/x/sys/windows"
+	"golang.org/x/sys/windows/registry"
 )
 
 // 进程级 DPI 感知：让窗口坐标 / WebView 渲染统一按物理像素工作。
@@ -232,6 +233,25 @@ func exeAppIconDataURL() string {
 	return "data:image/png;base64," + base64.StdEncoding.EncodeToString(img)
 }
 
+// webview2Available 检测 Windows 是否已安装 WebView2 Runtime。
+// webview_create（WEBVIEW_EDGE）失败的最常见原因是缺少 WebView2 Runtime，
+// 检测其安装注册表键（EdgeUpdate Clients GUID）判断状态，便于给出可操作提示。
+// 返回值仅用于决定错误文案，不参与窗口创建逻辑。
+func webview2Available() bool {
+	guid := `{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}`
+	key := `SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\` + guid
+	if k, err := registry.OpenKey(registry.LOCAL_MACHINE, key, registry.QUERY_VALUE|registry.READ); err == nil {
+		k.Close()
+		return true
+	}
+	key2 := `SOFTWARE\Microsoft\EdgeUpdate\Clients\` + guid
+	if k, err := registry.OpenKey(registry.LOCAL_MACHINE, key2, registry.QUERY_VALUE|registry.READ); err == nil {
+		k.Close()
+		return true
+	}
+	return false
+}
+
 func isZoomed(hwnd uintptr) bool {
 	r, _, _ := procIsZoomed.Call(hwnd)
 	return r != 0

package/templates/go/webview_go/webview.go

@@ -199,6 +199,13 @@ func New(debug bool) WebView { return NewWindow(debug, nil) }
 func NewWindow(debug bool, window unsafe.Pointer) WebView {
 	w := &webview{}
 	w.w = C.webview_create(boolToInt(debug), window)
+	// B55：webview_create 在目标平台 WebView 初始化失败时可能返回 NULL
+	//（如 Linux 缺 WebKitGTK、macOS WebKit 不可用），此时返回 nil 让调用方
+	//（freedom.go Run 的 w == nil 分支）走失败提示，而非持 nil webview_t
+	// 继续调用 SetTitle/SetSize/Init 等 C API 触发空指针崩溃。
+	if w.w == nil {
+		return nil
+	}
 	return w
 }
 
@@ -209,52 +216,85 @@ func (w *webview) Destroy() {
 }
 
 func (w *webview) Run() {
+	if destroyed.Load() {
+		return
+	}
 	C.webview_run(w.w)
 }
 
 func (w *webview) Terminate() {
+	if destroyed.Load() {
+		return
+	}
 	C.webview_terminate(w.w)
 }
 
 func (w *webview) Window() unsafe.Pointer {
+	if destroyed.Load() {
+		return nil
+	}
 	return C.webview_get_window(w.w)
 }
 
 func (w *webview) Navigate(url string) {
+	if destroyed.Load() {
+		return
+	}
 	s := C.CString(url)
 	defer C.free(unsafe.Pointer(s))
 	C.webview_navigate(w.w, s)
 }
 
 func (w *webview) SetHtml(html string) {
+	if destroyed.Load() {
+		return
+	}
 	s := C.CString(html)
 	defer C.free(unsafe.Pointer(s))
 	C.webview_set_html(w.w, s)
 }
 
 func (w *webview) SetTitle(title string) {
+	if destroyed.Load() {
+		return
+	}
 	s := C.CString(title)
 	defer C.free(unsafe.Pointer(s))
 	C.webview_set_title(w.w, s)
 }
 
 func (w *webview) SetDecorated(decorated bool) {
+	if destroyed.Load() {
+		return
+	}
 	C.webview_set_decorated(w.w, boolToInt(decorated))
 }
 
 func (w *webview) WindowControl(action WindowAction) int {
+	if destroyed.Load() {
+		return -1
+	}
 	return int(C.webview_window_control(w.w, C.webview_window_action_t(action)))
 }
 
 func (w *webview) BeginMoveDrag() int {
+	if destroyed.Load() {
+		return -1
+	}
 	return int(C.webview_window_begin_move_drag(w.w))
 }
 
 func (w *webview) SetSize(width int, height int, hint Hint) {
+	if destroyed.Load() {
+		return
+	}
 	C.webview_set_size(w.w, C.int(width), C.int(height), C.webview_hint_t(hint))
 }
 
 func (w *webview) Init(js string) {
+	if destroyed.Load() {
+		return
+	}
 	s := C.CString(js)
 	defer C.free(unsafe.Pointer(s))
 	C.webview_init(w.w, s)
@@ -294,6 +334,11 @@ func _webviewDispatchGoCallback(index unsafe.Pointer) {
 	delete(dispatch, uintptr(index))
 	m.Unlock()
 	if f != nil {
+		// 入队时 destroyed 可能为 false，但回调真正执行时窗口可能已销毁，
+		// 二次检查：销毁后 UI 线程即将退出，未执行的派发任务直接丢弃。
+		if destroyed.Load() {
+			return
+		}
 		f()
 	}
 }
@@ -335,6 +380,9 @@ func _webviewBindingGoCallback(w C.webview_t, id *C.char, req *C.char, index uin
 }
 
 func (w *webview) Bind(name string, f interface{}) error {
+	if destroyed.Load() {
+		return errors.New("freedom: webview destroyed")
+	}
 	v := reflect.ValueOf(f)
 	// f must be a function
 	if v.Kind() != reflect.Func {
@@ -413,6 +461,9 @@ func (w *webview) Bind(name string, f interface{}) error {
 }
 
 func (w *webview) Unbind(name string) error {
+	if destroyed.Load() {
+		return errors.New("freedom: webview destroyed")
+	}
 	// 清理 Go 侧 bindings / bindNames 条目，避免 Unbind 后永久泄漏。
 	// C 侧 binding_context（glue.c calloc，每 Bind 约 16B）在 C++ unbind 中
 	// 仅 erase map 不 free，会小幅泄漏；但框架内 Bind 次数固定（3~4 个）、