botmux 3.18.9 → 3.18.11

package/README.en.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/botmux"><img src="https://img.shields.io/npm/v/botmux.svg" alt="npm"></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="Node >= 22">
+  <img src="https://img.shields.io/badge/binary-no%20Node%20required-brightgreen.svg" alt="self-contained binary, no Node required">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
   <a href="https://github.com/deepcoldy/botmux"><img src="https://img.shields.io/github/stars/deepcoldy/botmux.svg?style=social" alt="Stars"></a>
 </p>
@@ -39,11 +39,30 @@ A daemon watches Lark messages and spawns an isolated session process for each n
 > About 5 minutes: a single Lark QR scan in `botmux setup` creates the app, configures all permissions, and publishes a version in one flow (add `--no-open-platform-auto` to only create the app and skip the permission + publish automation, which you then complete manually; creating the app manually / pasting credentials is a separate option inside setup).
 
 ```bash
-npm install -g botmux        # requires Node >= 22
+curl -fsSL https://raw.githubusercontent.com/deepcoldy/botmux/master/install.sh | sh
 botmux setup                 # one scan to create the app → pick a CLI → pick a working dir (permissions + publish auto-configured)
 botmux start                 # start the daemon (botmux autostart enable for auto-start on boot)
 ```
 
+> botmux ships as a **self-contained single-file binary** with its runtime embedded — **neither installing nor running it needs Node on the machine** (whatever the AI coding CLI you bridge needs is its own matter). It installs to `~/.botmux/bin/botmux` (override with `BOTMUX_INSTALL_DIR`), picks the right binary for your OS/arch, verifies its SHA-256, and adds `~/.botmux/bin` to the startup file your shell actually reads (zsh / bash / fish each get the correct one), so **a new terminal has the command**.
+>
+> Nothing native is compiled during install (no Python / node-gyp / compiler): the PTY is already inside the binary. Supported: linux / macOS × x64 / arm64, with musl builds selected automatically on Alpine and similar. **On Windows, install inside WSL2** — the daemon needs PTY / tmux / Unix signals and does not run on native Windows; WSL2 reports as linux and is a fully supported first-class environment. An unsupported platform, or a binary that cannot run on this host, **fails with an explicit error and leaves your existing install untouched** rather than leaving you with a command that won't start.
+>
+> To upgrade: `botmux upgrade` (replaces the binary in place), or just **re-run the curl command** — also an in-place upgrade, and it won't append a second PATH line.
+
+<details>
+<summary>Already living in the Node ecosystem? npm works too (same binary)</summary>
+
+```bash
+npm install -g botmux        # requires Node >= 22 to run the install itself
+```
+
+The npm package carries **the same self-contained binary** (only the one matching your os/arch is installed); its postinstall points `~/.botmux/bin/botmux` at it and writes PATH the same way. So you end up with exactly **one** botmux version — no more "two Node versions each carrying their own global botmux, fighting each other / no idea which one I just updated".
+
+The only difference is **who installs it and who upgrades it later**: the npm path needs Node ≥ 22 to run the install itself and hands upgrades back to `npm i -g botmux@latest`; the curl path never touches Node. Once running, the two are identical — same binary, same commands.
+
+</details>
+
 Then DM the bot, or run `botmux dashboard` to create a group, and start chatting. Full steps (Lark international, manual permission / publish setup after `--no-open-platform-auto`, troubleshooting) are in the **[5-Minute Quickstart](https://deepcoldy.github.io/botmux/en/quickstart)**.
 
 ## Core Scenarios

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/botmux"><img src="https://img.shields.io/npm/v/botmux.svg" alt="npm"></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="Node >= 22">
+  <img src="https://img.shields.io/badge/binary-no%20Node%20required-brightgreen.svg" alt="self-contained binary, no Node required">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
   <a href="https://github.com/deepcoldy/botmux"><img src="https://img.shields.io/github/stars/deepcoldy/botmux.svg?style=social" alt="Stars"></a>
 </p>
@@ -39,27 +39,27 @@ Daemon 监听飞书消息，为每个新会话自动 spawn 一个独立的会话
 > 约 5 分钟：`botmux setup` 一次飞书扫码就连续建好应用、配全权限、发版（加 `--no-open-platform-auto` 则只建应用、跳过权限与发版的自动配置，之后需手动完成；手动创建 / 粘贴凭证是 setup 里的另一个选项）。
 
 ```bash
-npm install -g botmux        # 需要 Node >= 22 装包本身
+curl -fsSL https://raw.githubusercontent.com/deepcoldy/botmux/master/install.sh | sh
 botmux setup                 # 一次扫码建应用 → 选 CLI → 选工作目录（自动配权限 + 发版）
 botmux start                 # 启动 daemon（botmux autostart enable 设开机自启）
 ```
 
-> npm 包内已经带了对应平台的**自包含二进制**（按 os/arch 只装匹配的那一个），安装时会把 `~/.botmux/bin/botmux` 指向它。所以装完只有**一个** botmux 版本，不再出现「装了两个 Node 版本、各自带一份全局 botmux 互相打架 / 不知道更新了哪个」。把 `~/.botmux/bin` 放进 PATH 即可（安装日志会提示命令）。
+> botmux 本体是一个**自包含单文件二进制**，运行时已嵌在里面——**装它和跑它都不需要机器上有 Node**（你要接的 AI 编程 CLI 自己需要什么另算）。装到 `~/.botmux/bin/botmux`（`BOTMUX_INSTALL_DIR` 可改），按 OS/arch 自动选对应二进制、校验 SHA-256，并把 `~/.botmux/bin` 写进你当前 shell 的启动文件（zsh / bash / fish 各写对的那个），**开个新终端就能用**。
 >
-> 安装过程**不编译任何原生模块**（不需要 Python / node-gyp / 编译器）：要跑的 PTY 已经嵌在那个二进制里，npm 只是把它放到位。支持 linux / macOS × x64 / arm64；**Windows 请在 WSL2 里安装**（WSL 报告为 linux，是完整支持的一等环境）。不在支持列表里的平台会在安装时**明确报错**，而不是装上一个跑不起来的命令。
+> 安装过程**不编译任何原生模块**（不需要 Python / node-gyp / 编译器）：PTY 已经嵌在二进制里。支持 linux / macOS × x64 / arm64（Alpine 等 musl 环境自动选 musl 版）；**Windows 请在 WSL2 里安装**（daemon 依赖 PTY / tmux / Unix 信号，原生 Windows 跑不了；WSL2 报告为 linux，是完整支持的一等环境）。平台不在列表里、或下下来的二进制在本机跑不起来，安装会**明确报错并保留原有版本**，而不是装上一个起不来的命令。
+>
+> 升级：`botmux upgrade`（原地换二进制），或**重跑一遍上面那条 curl 命令**——同样原地升级，不会重复往启动文件里追加 PATH。
 
 <details>
-<summary>不想装 Node？直接下单文件可执行（连装包都不需要 Node）</summary>
-
-同一个自包含二进制也可以脱离 npm 直接下载，**自带运行时、不依赖机器上的任何 Node**。macOS / Linux：
+<summary>已经在用 Node 生态？也可以走 npm（同一个二进制）</summary>
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/deepcoldy/botmux/master/install.sh | sh
-botmux setup
-botmux start
+npm install -g botmux        # 需要 Node >= 22 装包本身
 ```
 
-装到 `~/.botmux/bin/botmux`（`BOTMUX_INSTALL_DIR` 可改），自动按 OS/arch 拉对应二进制并校验 SHA-256。命令用法与 npm 版完全一致。**Windows 请在 WSL2 里安装**（daemon 依赖 PTY / tmux / Unix 信号，原生 Windows 跑不了；WSL2 报告为 linux，完整支持）。
+npm 包内带的是**同一个自包含二进制**（按 os/arch 只装匹配的那一个），postinstall 把 `~/.botmux/bin/botmux` 指向它并同样写 PATH。所以装完只有**一个** botmux 版本，不再出现「装了两个 Node 版本、各自带一份全局 botmux 互相打架 / 不知道更新了哪个」。
+
+区别只在**谁来装、以后谁来升**：npm 路径需要 Node ≥ 22 才能执行安装本身，升级交回 `npm i -g botmux@latest`；curl 路径全程不碰 Node。跑起来之后两者完全一致——同样的二进制、同样的命令。
 
 </details>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botmux",
-  "version": "3.18.9",
+  "version": "3.18.11",
   "description": "Bridge between IM platforms and AI coding CLIs — one topic, one CLI session with live streaming",
   "type": "module",
   "files": [
@@ -80,12 +80,12 @@
   },
   "optionalDependencies": {
     "@napi-rs/canvas": "^0.1.65",
-    "botmux-darwin-arm64": "3.18.9",
-    "botmux-darwin-x64": "3.18.9",
-    "botmux-linux-arm64": "3.18.9",
-    "botmux-linux-arm64-musl": "3.18.9",
-    "botmux-linux-x64": "3.18.9",
-    "botmux-linux-x64-musl": "3.18.9"
+    "botmux-darwin-arm64": "3.18.11",
+    "botmux-darwin-x64": "3.18.11",
+    "botmux-linux-arm64": "3.18.11",
+    "botmux-linux-arm64-musl": "3.18.11",
+    "botmux-linux-x64": "3.18.11",
+    "botmux-linux-x64-musl": "3.18.11"
   },
   "devDependencies": {
     "@midscene/web": "^1.7.6",

package/scripts/postinstall-bin.mjs

@@ -16,19 +16,49 @@
  *
  * ── THE GUARD (do not loosen this) ──────────────────────────────────────────────
  * We only write the launcher for a REAL global install. Empirically measured what
- * npm/pnpm expose to postinstall (not assumed — probed all three cases):
+ * each package manager exposes to postinstall (not assumed — probed every case):
  *
  *   `npm i -g botmux`                    → npm_config_global === "true"
  *   installed as someone's local dep     → npm_config_global ABSENT
  *   `pnpm install` INSIDE the botmux repo → npm_config_global ABSENT
+ *   `bun add -g botmux`                  → npm_config_global ABSENT (see below)
  *
  * The third case is the dangerous one: a repo-local `pnpm install` DOES run the
  * root package's postinstall. So a `!== "false"` style check would fire during
  * ordinary development and rewrite ~/.botmux/bin/botmux — hijacking the global
  * launcher of whatever fleet shares that HOME (on the dev box that is ~50 live
- * daemons). Hence the guard is a STRICT `=== "true"`, and there is a second,
+ * daemons). Hence the env check stays a STRICT `=== "true"`, and there is a second,
  * independent bail-out when we can see we are inside the source checkout.
  *
+ * ⚠️ THE FOURTH CASE IS WHY THE ENV CHECK ALONE IS NOT ENOUGH. Bun does pass a few
+ * npm_* vars to lifecycle scripts — MEASURED with a probe package whose postinstall
+ * dumped its own env, the complete set is:
+ *
+ *   BUN_INSTALL, BUN_WHICH_IGNORE_CWD, npm_config_user_agent, npm_execpath,
+ *   npm_node_execpath
+ *
+ * — but `npm_config_global` is NOT among them, and that is the one this guard read.
+ * So for a perfectly real `bun add -g botmux` the check failed and this script
+ * exited 0 without writing anything. MEASURED end to end: `.bun/bin/` empty, no
+ * launcher, the platform binary sitting in the download cache, i.e. the user had NO
+ * `botmux` command at all. Worse, the obvious workaround did NOT help: `bun pm -g
+ * trust botmux` made bun report `1 script ran` while this script still wrote
+ * nothing, because the env check had already failed.
+ *
+ * ⚠️ TWO SEPARATE LAYERS — do not conflate them. (a) bun BLOCKS the script by
+ * default (`Blocked N postinstalls`); `bun pm trust` lifts that. (b) even once it
+ * runs, this guard killed it. Fixing (b) is what makes `bun pm trust` an actually
+ * working workaround. pnpm 10/11 is a different layer again: `onlyBuiltDependencies`
+ * means the script does not run at all, so this fix alone does not rescue pnpm —
+ * that needs approve-builds/onlyBuiltDependencies or a different mechanism.
+ *
+ * So the global check is: the env says global (npm/yarn), OR THE INSTALL LOCATION
+ * ITSELF says global. The layout list is INLINED in `locationSaysGlobal` below —
+ * see the ⚠️ notes there for why importing the repo's classifier from `dist/` was
+ * dead code in the published package, and why the inlined version is deliberately
+ * stricter on Windows. A source checkout matches no global layout (verified), so
+ * this cannot reopen the repo-local hijack that guard 2 also covers.
+ *
  * ── FAIL HARD WHEN THERE IS NO BINARY ──────────────────────────────────────────
  * This used to warn and exit 0, because `bin: {botmux: "dist/cli.js"}` gave every
  * failure a Node fallback to land on. That fallback is gone (it forced the main
@@ -102,10 +132,64 @@ function isMuslLinux() {
   return false;
 }
 
-// ── Guard 1: only a real `npm i -g` (strict equality; see header) ───────────────
-if (process.env.npm_config_global !== 'true') {
+// ── Guard 1: only a real global install ─────────────────────────────────────────
+// Two independent positive signals (see header). The env check is unchanged and
+// still strict; the location check is what makes `bun add -g` / `pnpm add -g` work,
+// since those provide no npm_config_* at all.
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = dirname(here); // scripts/ -> package root
+
+/**
+ * Does the install LOCATION say this is a package-manager-owned global tree?
+ *
+ * ⚠️ WHY THIS IS INLINED INSTEAD OF IMPORTING THE REPO'S CLASSIFIER. The first
+ * version did `await import('./dist/utils/global-install.js')` to reuse
+ * `detectGlobalInstallManager`. That was DEAD CODE in the published package: #1115
+ * removed `dist/` from `package.json` `files`, so the import always ENOENTs, the
+ * catch returned false, and the guard silently fell back to env-only — leaving
+ * `bun add -g botmux` exactly as broken as before. MEASURED, not reasoned:
+ *
+ *   git archive origin/master | tar x && npm pack
+ *   tar tzf botmux-*.tgz | grep -c '^package/dist/'    → 0
+ *
+ * and end to end, a real `bun add -g <that tarball>` then running this script the
+ * way bun does: exit 0, no launcher. This file is a standalone script with no build
+ * step, and neither `dist/` nor `src/` is published, so being SELF-CONTAINED is its
+ * natural form — inlining is not a compromise here.
+ *
+ * ⚠️ AND IT IS DELIBERATELY STRICTER THAN `detectGlobalInstallManager`. That
+ * function ends with `platform === 'win32' ? 'npm' : 'unknown'`, so on Windows it
+ * cannot tell a global install from a LOCAL dependency — MEASURED:
+ *
+ *   detectGlobalInstallManager('C:/projects/myapp/node_modules/botmux', 'win32') → 'npm'
+ *
+ * Harmless where it is used today (a wrong `npm i -g` merely reinstalls), but in
+ * THIS file it would mean a Windows local dependency repoints the shared
+ * `~/.botmux/bin/botmux` — the exact hijack guard 1 exists to prevent. So the list
+ * below recognises only KNOWN GLOBAL layouts and has no platform fallback. Windows
+ * npm globals are unaffected: they arrive with `npm_config_global=true` and never
+ * reach this check.
+ *
+ * The layout patterns mirror `detectGlobalInstallManager`'s; a source guard in
+ * test/npm-binary-distribution.test.ts pins the two in agreement over a matrix of
+ * real global paths, so the duplication cannot drift unnoticed.
+ */
+function locationSaysGlobal(root) {
+  const r = root.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+  // Every global layout below ends at the main package; anything else is not ours.
+  if (!r.endsWith('/node_modules/botmux')) return false;
+  return r.endsWith('/lib/node_modules/botmux')                    // npm, POSIX
+    || r.includes('/.bun/install/global/node_modules/botmux')      // bun
+    || r.includes('/bun/install/global/node_modules/botmux')       // bun, custom BUN_INSTALL
+    || r.includes('/.pnpm/')                                       // pnpm virtual store
+    || /\/pnpm\/global\/[^/]+\/node_modules\/botmux$/.test(r)      // pnpm 9 global
+    || /\/pnpm\/global\/v\d+\/[^/]+\/node_modules\/botmux$/.test(r) // pnpm 11 global
+    || /\/pnpm\/store\/v\d+\/links\/@\/botmux\//.test(r);          // pnpm 11 store links
+}
+
+if (process.env.npm_config_global !== 'true' && !locationSaysGlobal(pkgRoot)) {
   // Silent: this is the overwhelmingly common case (dev installs, transitive
-  // installs). Noise here would appear on every `pnpm install` in the repo.
+  // installs). Noise here would appear on every `bun install` in the repo.
   process.exit(0);
 }
 
@@ -113,8 +197,6 @@ if (process.env.npm_config_global !== 'true') {
 // Defence in depth for guard 1. If the package directory we are running from is a
 // git checkout of botmux (has .git and src/), this is a developer environment, not
 // an installed package — the launcher must not be repointed.
-const here = dirname(fileURLToPath(import.meta.url));
-const pkgRoot = dirname(here); // scripts/ -> package root
 if (existsSync(join(pkgRoot, '.git')) && existsSync(join(pkgRoot, 'src'))) {
   process.exit(0);
 }