termdock 1.4.362 → 1.4.363

package/README.en.md

@@ -52,6 +52,14 @@ sudo apt-get install -y tmux
 
 If `node-pty` needs compilation, install Xcode Command Line Tools on macOS (`xcode-select --install`), or `build-essential` and `python3` on Ubuntu / Debian. Behavior on WSL2, other Linux distributions, and mobile devices depends on the actual environment.
 
+On macOS, installation, startup repair, and automatic updates resolve the SDK, `clang`, and `clang++` from the selected Xcode / Command Line Tools, preserving explicit `DEVELOPER_DIR`, `SDKROOT`, `CC`, and `CXX` settings. To select Xcode for one installation without changing the global selection:
+
+```bash
+DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer" npm install -g termdock --foreground-scripts
+```
+
+For `tapi error` / `unknown architecture`, check the toolchain paths in the failure log, `xcode-select -p`, and `xcrun --sdk macosx --show-sdk-path`. Explicit SDK or compiler overrides must also belong to a compatible toolchain.
+
 ### Install and launch
 
 ```bash

package/README.md

@@ -52,6 +52,14 @@ sudo apt-get install -y tmux
 
 如果 `node-pty` 需要本机编译，macOS 安装 `xcode-select --install`，Ubuntu / Debian 安装 `build-essential` 和 `python3`。WSL2、不同 Linux 发行版和手机系统的具体行为请以实际环境为准。
 
+macOS 安装、启动修复和自动更新会从当前选中的 Xcode / Command Line Tools 解析配套的 SDK、`clang` 和 `clang++`，保留显式设置的 `DEVELOPER_DIR`、`SDKROOT`、`CC`、`CXX`。多套工具共存时，可仅为本次安装选择 Xcode（无需修改全局设置）：
+
+```bash
+DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer" npm install -g termdock --foreground-scripts
+```
+
+若出现 `tapi error` / `unknown architecture`，检查失败日志中的工具链路径，以及 `xcode-select -p` 和 `xcrun --sdk macosx --show-sdk-path`；已有的 SDK 或编译器覆盖也需要来自配套工具链。
+
 ### 安装并启动
 
 ```bash

package/dist/server/utils/npmUpdate.js

@@ -3,7 +3,9 @@ import { promisify } from 'node:util';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 const execFileAsync = promisify(execFile);
+const require = createRequire(import.meta.url);
 export const OFFICIAL_NPM_REGISTRY = 'https://registry.npmjs.org';
 const TERMDOCK_PACKAGE = 'termdock';
 const NPM_QUERY_TIMEOUT_MS = 30_000;
@@ -120,20 +122,8 @@ export function npmRuntimeEnvironment(execPath = process.execPath, env = process
     return { ...env, PATH: [path.dirname(execPath), ...systemBins, env.PATH].filter(Boolean).join(path.delimiter) };
 }
 async function installEnvironment() {
-    const env = npmRuntimeEnvironment();
-    if (process.platform === 'darwin') {
-        // New CLT releases can leave node-gyp's implicit libc++ search path stale.
-        // Use the SDK selected by xcrun without changing the user's global setup.
-        const { stdout } = await execFileAsync('/usr/bin/xcrun', ['--show-sdk-path'], { timeout: 5000, env });
-        const sdk = stdout.trim();
-        const headers = path.join(sdk, 'usr/include/c++/v1');
-        if (!path.isAbsolute(sdk) || !fs.existsSync(path.join(headers, 'functional'))) {
-            throw new Error('macOS C++ SDK headers are unavailable. Install or repair Command Line Tools, then retry.');
-        }
-        env.SDKROOT = sdk;
-        env.CPLUS_INCLUDE_PATH = [headers, env.CPLUS_INCLUDE_PATH].filter(Boolean).join(path.delimiter);
-    }
-    return env;
+    const { nativeBuildEnvironment } = require('../../../scripts/native-build-env.cjs');
+    return nativeBuildEnvironment(npmRuntimeEnvironment());
 }
 function npmExecutable() {
     return process.platform === 'win32' ? 'npm.cmd' : 'npm';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termdock",
-  "version": "1.4.362",
+  "version": "1.4.363",
   "description": "A complete web-based terminal application with modern UI",
   "type": "module",
   "main": ".desktop-dist/main.js",
@@ -44,7 +44,7 @@
     "trace:fsio": "node scripts/inspect-fs-io.mjs",
     "release:classify": "node scripts/classify-release.mjs",
     "test": "vitest --passWithNoTests",
-    "test:initialization": "node --test tests/nodePtyInstall.test.mjs tests/installUtils.test.mjs && node --import tsx --test tests/initialization.process.test.mjs && vitest run --maxWorkers=2 src/server/utils/bootCheck.test.ts src/server/utils/localHttpsSetup.test.ts src/server/utils/nodePtyCleanup.test.ts",
+    "test:initialization": "node --test tests/nodePtyInstall.test.mjs tests/installUtils.test.mjs && node --import tsx --test tests/initialization.process.test.mjs && vitest run --maxWorkers=2 src/server/utils/bootCheck.test.ts src/server/utils/localHttpsSetup.test.ts src/server/utils/nodePtyCleanup.test.ts src/server/utils/npmUpdate.test.ts",
     "test:initialization:real": "node --import tsx --test tests/initialization.real.test.mjs",
     "test:webgl": "vitest run --config vitest.webgl.config.ts",
     "test:terminal-geometry": "vitest run src/lib/terminal/geometry.test.ts src/lib/terminal/geometryBoundary.test.ts src/lib/terminal/fitHysteresis.test.ts src/lib/terminal/api.continuousReconnect.test.ts src/lib/components/terminal/TerminalViewportPasteOwnership.test.tsx src/lib/federation/SessionAccessView.test.tsx src/server/utils/tmuxDisplayGeometry.test.ts src/server/utils/tmuxObserverSize.test.ts src/server/utils/tmuxSizeOwnership.test.ts src/server/utils/terminalHandshakeDimensions.test.ts src/server/routes/terminalInitialSize.test.ts src/server/routes/terminalSampling.test.ts",

package/runtime-manifest.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
   "packageName": "termdock",
-  "version": "1.4.362",
+  "version": "1.4.363",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-Y8lMrpp3Lu4r/I8Zx3R59DZsC3RtYVYC7b/kH84ZMeY=",
-  "serverBundleHash": "sha256-VjBxIqUXYHaLL54xK2i0qlhY6BRDJbgZXP9mAI4s5pk=",
+  "serverBundleHash": "sha256-vTdrZVQ5FX778s9lGNFOgKR2oMpKcNS3xb6BYf0YQr0=",
   "clientBundleHash": "sha256-Y5z0lKMQXjjKtUKjCVqX14u7Zh92XcJpDgwJ+kfsvZs=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"

package/scripts/ensure-node-pty.cjs

@@ -3,14 +3,16 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { createHash } = require('node:crypto');
 const { spawnSync } = require('node:child_process');
+const { nativeBuildEnvironment } = require('./native-build-env.cjs');
 const hash = data => createHash('sha256').update(data).digest('hex');
 const upstreamHash = '5e1005d6bdcfbe97b486ee415419fe7adae99035047f07340fbad36419e0bae6';
 
 function rebuildNodePty(ptyRoot, { timeout = 180_000, patched = false } = {}) {
+  const env = nativeBuildEnvironment();
   // npm install -g passes npm_config_global=true to lifecycle scripts. Do not
   // let it turn npx's temporary dependency installation into a global install.
   const result = spawnSync('npx', ['--global=false', '--yes', 'node-gyp', 'rebuild'], {
-    cwd: ptyRoot, stdio: 'inherit', timeout,
+    cwd: ptyRoot, stdio: 'inherit', timeout, env,
   });
   if (result.error || result.status !== 0) {
     const context = [
@@ -18,6 +20,8 @@ function rebuildNodePty(ptyRoot, { timeout = 180_000, patched = false } = {}) {
       `exit status=${result.status ?? 'none'}`,
       ...(result.signal ? [`signal=${result.signal}`] : []),
       ...(result.error ? [`${result.error.code || 'spawn error'}: ${result.error.message}`] : []),
+      ...(process.platform === 'darwin'
+        ? ['DEVELOPER_DIR', 'SDKROOT', 'CC', 'CXX'].map(key => `${key}=${env[key] || '(unset)'}`) : []),
     ].join('; ');
     throw new Error(`${patched ? 'Patched node-pty' : 'node-pty'} rebuild failed (${context}). `
       + 'See the npx/node-gyp output above for the cause. Check npm/cache errors before changing build tools; '

package/scripts/native-build-env.cjs

@@ -0,0 +1,47 @@
+// Keep macOS compiler and SDK discovery in one place for install and repair.
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+function nativeBuildEnvironment(inherited = process.env, platform = process.platform) {
+  const env = { ...inherited };
+  if (platform !== 'darwin' || (env.SDKROOT && env.CC && env.CXX)) return env;
+
+  function resolve(command, args, directory) {
+    const result = spawnSync(command, args, { env, encoding: 'utf8', timeout: 5000 });
+    const value = result.stdout?.trim();
+    let valid = false;
+    if (!result.error && result.status === 0 && value && path.isAbsolute(value)) {
+      try {
+        valid = directory ? fs.statSync(value).isDirectory() : fs.statSync(value).isFile();
+        if (!directory) fs.accessSync(value, fs.constants.X_OK);
+      } catch { valid = false; }
+    }
+    if (!valid) {
+      const detail = result.error?.message || result.stderr?.trim() || `exit status=${result.status}; output=${JSON.stringify(value)}`;
+      throw new Error(`Cannot resolve macOS native build tools: ${command} ${args.join(' ')} (${detail}). `
+        + `DEVELOPER_DIR=${env.DEVELOPER_DIR || '(xcode-select default)'}. `
+        + 'Check xcode-select -p and xcrun --sdk macosx --show-sdk-path, or explicitly set matching DEVELOPER_DIR, SDKROOT, CC and CXX for this install.',
+      result.error ? { cause: result.error } : undefined);
+    }
+    return value;
+  }
+
+  // Pin the selection for every xcrun query and for node-gyp. Never change the
+  // machine-wide xcode-select setting or replace explicit compiler/SDK choices.
+  env.DEVELOPER_DIR ||= resolve('/usr/bin/xcode-select', ['-p'], true);
+  // The explicit SDK name matters: bare --show-sdk-path can select the CLT SDK
+  // even when an older Xcode is selected (nodejs/node-gyp#3344).
+  env.SDKROOT ||= resolve('/usr/bin/xcrun', ['--sdk', 'macosx', '--show-sdk-path'], true);
+  // gyp treats CC/CXX as shell commands, so a discovered path needs quoting
+  // when an Xcode directory contains spaces. Explicit commands stay verbatim.
+  const compiler = name => {
+    const file = resolve('/usr/bin/xcrun', ['--sdk', 'macosx', '--find', name], false);
+    return /^[\w/.:+-]+$/.test(file) ? file : `'${file.replaceAll("'", "'\\''")}'`;
+  };
+  env.CC ||= compiler('clang');
+  env.CXX ||= compiler('clang++');
+  return env;
+}
+
+module.exports = { nativeBuildEnvironment };