fix CI

Author: Jacobinwwey

TODO.md

@@ -1,3 +1,81 @@
+# 2026-03-08 v1.5.16 - High-Priority Closure (Transport + Storage + Cross-Platform Godot Strategy)
+
+## English Document
+
+### Objective
+Close all open high-priority items from `v1.5.15` with implementation + regression validation, without weakening existing desktop/mobile runtime boundaries.
+
+### Completed in This Iteration
+- [x] **Transport modernization closure**:
+  - [x] Added JSON-RPC-compatible bridge envelopes in `src/frontend/runtime_bridge.js` (`toBridgeEnvelope`, `parseBridgeEnvelope`, `sendBridgeMessage`) while keeping legacy `type/payload` compatibility.
+  - [x] Migrated `src/frontend/path_app.js` bridge sends/receives to the runtime transport adapter path (`_sendBridgeMessage`, `_parseBridgeIncomingMessage`) instead of direct raw message formatting/parsing.
+- [x] **Storage-provider abstraction closure**:
+  - [x] Added `src/frontend/storage_provider.js` as the unified runtime storage provider and wired it into source/reader flows.
+  - [x] Implemented provider branches for sidecar HTTP, Tauri invoke commands, and Capacitor-native filesystem read/list fallbacks (`Filesystem` plugin-aware helpers) while preserving current capability gating policy.
+- [x] **Explicit macOS/Linux Godot sidecar artifact strategy**:
+  - [x] Reworked `scripts/ensure-godot-sidecar.js` into host-aware preparation for Windows/Linux/macOS naming (`godot-<target-triple>`), with deterministic lookup strategy and documented env overrides.
+  - [x] Updated `src-tauri/src/lib.rs` Godot executable resolution to platform-specific sidecar names + host aliases, with tests adjusted for cross-platform behavior.
+- [x] **Release policy explicitness kept in code/docs surface**:
+  - [x] Capacitor native remains bounded read-only/cache-oriented in runtime capability handling.
+  - [x] README policy statements remain explicit that Capacitor path does not provide desktop sidecar parity yet.
+
+### High-Priority Status
+- [x] Complete transport modernization (replace remaining raw desktop HTTP/WS flows with Tauri-native IPC or JSON-RPC adapter).
+- [x] Implement storage-provider abstraction across desktop sidecar, Tauri commands, and Capacitor native filesystem.
+- [x] Add explicit macOS/Linux Godot sidecar artifact strategy (currently Windows binary workflow is strongest).
+- [x] Keep release policy explicit: Capacitor native remains read-only packaged mode until parity work is delivered.
+
+### Verification Gate (Executed)
+- [x] `npx tsc --pretty false`
+- [x] `npx jest src/storage.provider.contract.test.ts src/source_manager.loadflow.test.ts src/runtime.capabilities.test.ts src/runtime.transport.adapter.contract.test.ts --runInBand`
+- [x] `npm run test:migration`
+- [x] `npm run test:tauri`
+- [x] `./src-tauri/bin/godot-x86_64-pc-windows-msvc.exe --headless --path ./path_mode --quit`
+- [x] `npm run build:sidecar`
+- [x] `npm run build:sidecar:all` (artifact generation + validation; macOS binary signing warning remains expected when built off macOS host)
+- [x] `npm run verify:tauri:bin`
+- [x] `npm test`
+
+---
+
+## 中文文档
+
+### 目标
+在不削弱现有桌面端/移动端运行时边界的前提下，完成 `v1.5.15` 中全部“高优先级”未闭环事项，并提供完整回归验证证据。
+
+### 本轮完成
+- [x] **传输层现代化闭环**：
+  - [x] 在 `src/frontend/runtime_bridge.js` 增加 JSON-RPC 兼容桥接信封能力（`toBridgeEnvelope`、`parseBridgeEnvelope`、`sendBridgeMessage`），同时保持旧版 `type/payload` 兼容。
+  - [x] 将 `src/frontend/path_app.js` 的桥接收发迁移到统一运行时传输适配路径（`_sendBridgeMessage`、`_parseBridgeIncomingMessage`），不再直接手写原始消息格式解析。
+- [x] **存储抽象闭环**：
+  - [x] 新增 `src/frontend/storage_provider.js` 作为统一存储提供者，并接入 source/reader 关键流程。
+  - [x] 提供 sidecar HTTP、Tauri invoke、Capacitor 原生文件系统读/列目录回退分支（包含 `Filesystem` 插件感知），同时保持现行能力门禁策略不变。
+- [x] **macOS/Linux Godot sidecar 制品策略显式化**：
+  - [x] 将 `scripts/ensure-godot-sidecar.js` 重构为主机平台感知策略，支持 Windows/Linux/macOS 目标命名（`godot-<target-triple>`）、确定性查找链路与环境变量覆写入口。
+  - [x] 更新 `src-tauri/src/lib.rs` 的 Godot 可执行文件解析逻辑，改为平台侧车命名 + 主机别名解析；并同步调整测试确保跨平台行为一致。
+- [x] **发布边界显式性持续保持**：
+  - [x] Capacitor 原生保持受限的只读/缓存导向运行时能力边界。
+  - [x] README 中继续明确 Capacitor 路径尚未达到桌面 sidecar 等价能力。
+
+### 高优先级状态
+- [x] 完成传输层现代化（将剩余桌面端原始 HTTP/WS 调用迁移到 Tauri 原生命令或 JSON-RPC 适配层）。
+- [x] 实现跨运行时存储抽象（桌面 sidecar / Tauri commands / Capacitor 文件系统）。
+- [x] 制定并落地 macOS/Linux 的 Godot sidecar 制品策略（当前 Windows 二进制链路最完整）。
+- [x] 持续保持发布边界清晰：在能力对齐完成前，Capacitor 原生仍为只读打包模式。
+
+### 验证门禁（已执行）
+- [x] `npx tsc --pretty false`
+- [x] `npx jest src/storage.provider.contract.test.ts src/source_manager.loadflow.test.ts src/runtime.capabilities.test.ts src/runtime.transport.adapter.contract.test.ts --runInBand`
+- [x] `npm run test:migration`
+- [x] `npm run test:tauri`
+- [x] `./src-tauri/bin/godot-x86_64-pc-windows-msvc.exe --headless --path ./path_mode --quit`
+- [x] `npm run build:sidecar`
+- [x] `npm run build:sidecar:all`（已完成制品构建与校验；在非 macOS 主机构建时出现 macOS 签名警告属预期）
+- [x] `npm run verify:tauri:bin`
+- [x] `npm test`
+
+---
+
 # 2026-03-08 v1.5.15 - Fixrisk Phase-1 Hardening Execution (Completed)
 
 ## English Document

jest.config.js

@@ -8,4 +8,6 @@ module.exports = {
   transform: {
     ...tsJestTransformCfg,
   },
-};
+  // Only run source tests; compiled dist tests are build artifacts and can resolve paths incorrectly.
+  testPathIgnorePatterns: ["/node_modules/", "/dist/", "/ref/"],
+};

package.json

@@ -38,7 +38,7 @@
     "smoke:sidecar:relaunch": "node scripts/smoke-sidecar-relaunch.js",
     "smoke:android:pathmode": "node scripts/smoke-android-pathmode.js",
     "test:mobile:contracts": "jest src/mobile.pipeline.test.ts src/runtime.capabilities.test.ts src/source_manager.loadflow.test.ts src/capacitor.runtime.contract.test.ts src/android.pathmode.contract.test.ts src/android.pathmode.smoke.contract.test.ts --runInBand",
-    "test:migration": "jest src/core/Graph.test.ts src/core/PathEngine.test.ts src/core/TreeLayout.test.ts src/backend/algorithms/CycleDetection.test.ts src/utils/RuntimePaths.test.ts src/server.migration.test.ts src/mobile.pipeline.test.ts src/runtime.capabilities.test.ts src/runtime.transport.adapter.contract.test.ts src/source_manager.loadflow.test.ts src/capacitor.runtime.contract.test.ts src/welcome.loadflow.test.ts src/pathmode.history.contract.test.ts src/android.pathmode.contract.test.ts src/android.pathmode.smoke.contract.test.ts src/pathbridge.handshake.contract.test.ts --runInBand",
+    "test:migration": "jest src/core/Graph.test.ts src/core/PathEngine.test.ts src/core/TreeLayout.test.ts src/backend/algorithms/CycleDetection.test.ts src/utils/RuntimePaths.test.ts src/server.migration.test.ts src/mobile.pipeline.test.ts src/runtime.capabilities.test.ts src/runtime.transport.adapter.contract.test.ts src/storage.provider.contract.test.ts src/source_manager.loadflow.test.ts src/capacitor.runtime.contract.test.ts src/welcome.loadflow.test.ts src/pathmode.history.contract.test.ts src/android.pathmode.contract.test.ts src/android.pathmode.smoke.contract.test.ts src/pathbridge.handshake.contract.test.ts --runInBand",
     "test:tauri": "node scripts/cleanup-tauri-sidecars.js && node scripts/ensure-tauri-frontend-dist.js && cargo test --manifest-path src-tauri/Cargo.toml",
     "test:gates": "npm run test:migration && npm run test:tauri && npm run verify:android:env",
     "prepublishOnly": "npm run build",

path_mode/scripts/path_mode_ui.gd

@@ -26,6 +26,9 @@ const TREE_VIEW_SCENE = preload("res://scenes/tree_view_panel.tscn")
 const SETTINGS_SCENE = preload("res://scenes/settings_panel.tscn")
 const READER_RENDER_CLIENT_SCRIPT = preload("res://scripts/reader_render_client.gd")
 const READER_IMAGE_CANVAS_SCRIPT = preload("res://scripts/reader_image_canvas.gd")
+const SETTINGS_ICON := "⚙"
+const BG_UNLOCKED_ICON := "🔓"
+const BG_LOCKED_ICON := "🔒"
 const READER_DISPLAY_MATH_PREVIEW_MAX_SIZE := Vector2(560.0, 180.0)
 const READER_DISPLAY_MERMAID_PREVIEW_MAX_SIZE := Vector2(620.0, 420.0)
 const READER_MEDIA_PAGE_MARGIN := 72.0
@@ -246,7 +249,7 @@ func _create_dynamic_ui() -> void:
 
 		# Background lock button
 		_bg_lock_button = Button.new()
-		_bg_lock_button.text = "BG"
+		_bg_lock_button.text = BG_UNLOCKED_ICON
 		_bg_lock_button.tooltip_text = "Lock Background (camera won't rotate sky)"
 		_bg_lock_button.toggle_mode = true
 		_bg_lock_button.custom_minimum_size = Vector2(44, 34)
@@ -332,10 +335,9 @@ func _create_dynamic_ui() -> void:
 
 		_apply_button_style(_edit_button, Color(0.2, 0.24, 0.3, 1.0), Color(0.27, 0.31, 0.4, 1.0), Color(0.14, 0.18, 0.24, 1.0), Color(0.42, 0.46, 0.58, 1.0), Color(0.92, 0.95, 1.0, 1.0))
 
-	## Create Settings button as an independent floating control in the top-right corner
-	## ASCII comment retained here to avoid source-encoding issues.
+	## Create Settings button as an independent floating control in the top-right corner.
 	_settings_button = Button.new()
-	_settings_button.text = "SET"
+	_settings_button.text = SETTINGS_ICON
 	_settings_button.tooltip_text = "Settings"
 	_settings_button.custom_minimum_size = Vector2(44, 44)
 	_settings_button.anchor_left = 1.0
@@ -4176,7 +4178,7 @@ func _on_bg_lock_toggled(pressed: bool) -> void:
 	## Toggle background lock icon and emit signal
 	## Keep the background-lock label synchronized with the emitted state.
 	if _bg_lock_button:
-		_bg_lock_button.text = "BGL" if pressed else "BG"
+		_bg_lock_button.text = BG_LOCKED_ICON if pressed else BG_UNLOCKED_ICON
 		_bg_lock_button.tooltip_text = "Background locked" if pressed else "Lock Background (camera won't rotate sky)"
 	background_lock_toggled.emit(pressed)
 

scripts/ensure-godot-sidecar.js

@@ -4,6 +4,13 @@ const path = require('path');
 
 const MIN_GODOT_BINARY_BYTES = 1 * 1024 * 1024;
 
+const HOST_GODOT_BINARY = {
+  windows_x64: 'godot-x86_64-pc-windows-msvc.exe',
+  linux_x64: 'godot-x86_64-unknown-linux-gnu',
+  macos_arm64: 'godot-aarch64-apple-darwin',
+  macos_x64: 'godot-x86_64-apple-darwin',
+};
+
 function safeStat(filePath) {
   try {
     return fs.statSync(filePath);
@@ -25,6 +32,9 @@ function looksLikeGodotBinary(filePath) {
 function copyFile(source, target) {
   fs.mkdirSync(path.dirname(target), { recursive: true });
   fs.copyFileSync(source, target);
+  if (process.platform !== 'win32') {
+    fs.chmodSync(target, 0o755);
+  }
 }
 
 function addCandidate(list, filePath) {
@@ -34,105 +44,169 @@ function addCandidate(list, filePath) {
   }
 }
 
-function addGodotBinariesFromDir(list, dirPath) {
+function resolveHostGodotBinaryName() {
+  if (process.platform === 'win32' && process.arch === 'x64') {
+    return HOST_GODOT_BINARY.windows_x64;
+  }
+  if (process.platform === 'linux' && process.arch === 'x64') {
+    return HOST_GODOT_BINARY.linux_x64;
+  }
+  if (process.platform === 'darwin' && process.arch === 'arm64') {
+    return HOST_GODOT_BINARY.macos_arm64;
+  }
+  if (process.platform === 'darwin' && process.arch === 'x64') {
+    return HOST_GODOT_BINARY.macos_x64;
+  }
+  return null;
+}
+
+function hostBinaryNames() {
+  if (process.platform === 'win32') {
+    return ['godot.exe', 'godot4.exe', 'Godot_v4.3-stable_win64.exe'];
+  }
+  if (process.platform === 'darwin') {
+    return ['godot', 'godot4', 'Godot'];
+  }
+  return ['godot', 'godot4'];
+}
+
+function addBinariesFromDir(list, dirPath, hostNames) {
   if (!dirPath || !fs.existsSync(dirPath)) return;
+  for (const binaryName of hostNames) {
+    addCandidate(list, path.join(dirPath, binaryName));
+  }
+
   let entries = [];
   try {
     entries = fs.readdirSync(dirPath, { withFileTypes: true });
   } catch {
     return;
   }
 
-  const files = entries
-    .filter((entry) => entry.isFile() && /^godot.*\.exe$/i.test(entry.name))
-    .map((entry) => path.join(dirPath, entry.name))
-    .sort((a, b) => {
-      const aName = path.basename(a).toLowerCase();
-      const bName = path.basename(b).toLowerCase();
-      const aConsole = aName.includes('console');
-      const bConsole = bName.includes('console');
-      if (aConsole !== bConsole) {
-        return aConsole ? 1 : -1;
+  for (const entry of entries) {
+    if (!entry.isFile()) {
+      continue;
+    }
+    const normalized = entry.name.toLowerCase();
+    if (process.platform === 'win32') {
+      if (/^godot.*\.exe$/.test(normalized)) {
+        addCandidate(list, path.join(dirPath, entry.name));
       }
-      return aName.localeCompare(bName);
-    });
+      continue;
+    }
 
-  for (const file of files) {
-    addCandidate(list, file);
+    if (/^godot($|[^a-z0-9].*)/.test(normalized) || /^godot4($|[^a-z0-9].*)/.test(normalized)) {
+      addCandidate(list, path.join(dirPath, entry.name));
+    }
   }
 }
 
-function guessWindowsGodotDirs() {
-  if (process.platform !== 'win32') {
-    return [];
+function addKnownMacAppCandidates(list) {
+  if (process.platform !== 'darwin') {
+    return;
   }
+  addCandidate(list, '/Applications/Godot.app/Contents/MacOS/Godot');
+  addCandidate(list, '/Applications/Godot_mono.app/Contents/MacOS/Godot');
+}
 
+function guessHostSearchDirs() {
   const dirs = [];
   const userHome = os.homedir();
-  ['Downloads', 'downloads', 'Desktop', '下载', '网页下载'].forEach((name) => {
-    dirs.push(path.join(userHome, name));
-  });
-
-  // Try drive root download folders (for setups where downloads are moved to D:/E:).
-  const rootNames = ['Downloads', 'downloads', '下载', '网页下载'];
-  for (let code = 67; code <= 90; code += 1) { // C..Z
-    const drive = String.fromCharCode(code);
-    rootNames.forEach((name) => {
-      dirs.push(`${drive}:\\${name}`);
+
+  if (process.platform === 'win32') {
+    ['Downloads', 'downloads', 'Desktop', '下载', '网页下载'].forEach((name) => {
+      dirs.push(path.join(userHome, name));
     });
+    for (let code = 67; code <= 90; code += 1) {
+      const drive = String.fromCharCode(code);
+      ['Downloads', 'downloads', '下载', '网页下载'].forEach((name) => {
+        dirs.push(`${drive}:\\${name}`);
+      });
+    }
+    return dirs;
   }
 
+  dirs.push('/usr/local/bin', '/usr/bin', path.join(userHome, '.local', 'bin'));
+  if (process.platform === 'darwin') {
+    dirs.push('/opt/homebrew/bin', '/Applications');
+  }
   return dirs;
 }
 
+function shouldFailOnMissing() {
+  if (process.env.NOTE_CONNECTION_GODOT_REQUIRED === '1') {
+    return true;
+  }
+  return process.platform === 'win32';
+}
+
 const repoRoot = path.resolve(__dirname, '..');
 const sidecarDir = path.join(repoRoot, 'src-tauri', 'bin');
-const targetGodot = path.join(sidecarDir, 'godot-x86_64-pc-windows-msvc.exe');
-const localGodot = path.join(sidecarDir, 'godot.exe');
-const envGodot = process.env.NOTE_CONNECTION_GODOT_EXE;
+const hostGodotBinaryName = resolveHostGodotBinaryName();
 
-if (process.platform !== 'win32') {
-  console.log('[Godot] Skipping Windows-specific Godot sidecar preparation on non-Windows host.');
+if (!hostGodotBinaryName) {
+  console.log(
+    `[Godot] Skipping sidecar preparation: unsupported host platform/arch ${process.platform}/${process.arch}.`
+  );
   process.exit(0);
 }
 
+const targetGodot = path.join(sidecarDir, hostGodotBinaryName);
+const envGodot = process.env.NOTE_CONNECTION_GODOT_EXE;
+
 if (looksLikeGodotBinary(targetGodot)) {
   console.log(`[Godot] Sidecar binary ready: ${targetGodot}`);
   process.exit(0);
 }
 
 if (hasContent(targetGodot) && !looksLikeGodotBinary(targetGodot)) {
   const size = safeStat(targetGodot)?.size || 0;
-  console.warn(
-    `[Godot] Existing sidecar binary looks invalid (${size} bytes): ${targetGodot}`
-  );
+  console.warn(`[Godot] Existing sidecar binary looks invalid (${size} bytes): ${targetGodot}`);
 }
 
 const candidates = [];
 if (envGodot && /_console\.exe$/i.test(envGodot)) {
   addCandidate(candidates, envGodot.replace(/_console\.exe$/i, '.exe'));
 }
 addCandidate(candidates, envGodot);
-addCandidate(candidates, localGodot);
-addGodotBinariesFromDir(candidates, sidecarDir);
+addCandidate(candidates, path.join(sidecarDir, hostGodotBinaryName));
+
+const hostNames = hostBinaryNames();
+addBinariesFromDir(candidates, sidecarDir, hostNames);
 
 const customSearchDirs = (process.env.NOTE_CONNECTION_GODOT_SEARCH_DIRS || '')
   .split(path.delimiter)
   .map((segment) => segment.trim())
   .filter(Boolean);
 
-customSearchDirs.forEach((dirPath) => addGodotBinariesFromDir(candidates, dirPath));
-guessWindowsGodotDirs().forEach((dirPath) => addGodotBinariesFromDir(candidates, dirPath));
+for (const dirPath of customSearchDirs) {
+  addBinariesFromDir(candidates, dirPath, hostNames);
+}
 
-const source = candidates.find((candidate) => looksLikeGodotBinary(candidate));
+for (const dirPath of guessHostSearchDirs()) {
+  addBinariesFromDir(candidates, dirPath, hostNames);
+}
 
+addKnownMacAppCandidates(candidates);
+
+const source = candidates.find((candidate) => looksLikeGodotBinary(candidate));
 if (!source) {
-  console.error('[Godot] Missing usable Godot binary for Tauri sidecar.');
-  console.error(
-    `[Godot] The sidecar target must be a real Godot executable (>= ${MIN_GODOT_BINARY_BYTES} bytes).`
-  );
-  console.error('[Godot] Provide NOTE_CONNECTION_GODOT_EXE, NOTE_CONNECTION_GODOT_SEARCH_DIRS, or place a non-wrapper godot.exe in src-tauri/bin.');
-  process.exit(1);
+  const strategyLines = [
+    `[Godot] Missing usable host binary for ${process.platform}/${process.arch}.`,
+    `[Godot] Expected target: ${targetGodot}`,
+    '[Godot] Strategy:',
+    '  1) Install a native Godot executable on this host.',
+    `  2) Set NOTE_CONNECTION_GODOT_EXE to that executable, or place it at ${targetGodot}.`,
+    '  3) Optionally set NOTE_CONNECTION_GODOT_SEARCH_DIRS for additional lookup directories.'
+  ];
+  strategyLines.forEach((line) => console.warn(line));
+
+  if (shouldFailOnMissing()) {
+    process.exit(1);
+  }
+
+  console.warn('[Godot] Continuing without a prepared host Godot sidecar binary.');
+  process.exit(0);
 }
 
 copyFile(source, targetGodot);