macOS：在应用程序目录外启动时支持便携数据模式

architecture/notes/nebula_app/platform/2026-09-28-macos-portable-startup.md

@@ -0,0 +1,44 @@
+# macOS portable startup storage
+
+## Status
+
+Implemented; pending review and native dialog acceptance.
+
+## Context
+
+Moving Pebrel.app alone leaves settings on the host. Storage must be selected before migration, logging, path caches or workers start.
+
+## Evidence
+
+The existing shared settings directory controls configuration, sessions and history. A macOS application bundle supplies a stable location from which to derive a sibling data directory after a move. The startup adapter and its focused tests document the current behavior.
+
+Native acceptance on head `99898d1` clicked the startup choices and created the marker, then the application panicked before publishing its runtime endpoint. RFD 0.17.2's synchronous dialog creates the shared NSApplication in its policy manager; GPUI requires its own application subclass and platform ivar when its event loop starts.
+
+## Decision
+
+A macOS bundle outside `/Applications`, `/System/Applications` and `~/Applications` offers portable, normal or quit. Explicit configuration and unbundled executables retain their existing behavior. Portable mode stores data in sibling `Pebrel Data`, remembers acceptance with `.pebrel-portable`, and sets both configuration directory aliases plus `TMPDIR` before workers start. CLI helpers use an existing portable store without a prompt. Portable startup skips host legacy migration. A linked or unwritable data root stops portable startup. An eligible translocated bundle without an explicit override stops before any launch choice rather than falling back to host settings.
+
+Startup uses the same Core Foundation native alert directly, without initializing AppKit. The existing transitive `objc2-core-foundation` dependency becomes an explicit macOS dependency for its typed bindings; no additional library or version is introduced.
+
+## Rejected alternatives
+
+- A new container format would change every persistence consumer.
+- Writing inside the signed bundle would make data depend on application replacement.
+- Persisting an absolute data path would break when the app and data move together.
+- Initializing the GPUI platform before storage selection would start workers before process-wide configuration overrides are set.
+
+## Consequences
+
+Users move Pebrel.app and `Pebrel Data` together after quitting. Existing preferences can be imported using Backup. System credentials, SSH keys, external tools, project files and OS caches remain outside the portable directory; live processes and absolute paths in user configuration do not migrate. Windows and Linux startup remain unchanged.
+
+## Validation
+
+Focused tests cover bundle location, relaunch, folder moves, unavailable or redirected storage, and localized choices. Native compilation and actual dialog interaction require separate evidence.
+
+## Supersedes
+
+None.
+
+## Revisit when
+
+Another platform needs portable storage or automatic profile migration has an explicit compatibility contract and native verification.

nebula_app/Cargo.toml

@@ -183,6 +183,7 @@ png = { version = "0.17.5", default-features = false, optional = true }
 [target.'cfg(target_os = "macos")'.dependencies]
 security-framework = "=3.7.0"
 objc2 = "0.6.1"
+objc2-core-foundation = { version = "0.3.1", default-features = false, features = ["std", "CFString", "CFUserNotification"] }
 objc2-foundation = { version = "0.3.1", default-features = false, features = [
     "std",
     "NSString",

nebula_app/i18n/en-US.json

@@ -1263,6 +1263,19 @@
     "relay_invalid": "Invalid configuration. Import connection details exported by pebrel-relay, or complete the address, room, tokens and fingerprint.",
     "relay_read_failed": "Reading did not complete. Check the SSH connection and that pebrel-relay is installed."
   },
+  "startup": {
+    "portable": {
+      "title": "Portable mode",
+      "description": "Pebrel is outside Applications. Store its data beside the app in {path}?",
+      "enable": "Use portable mode",
+      "normal": "Use normal mode",
+      "quit": "Quit",
+      "translocated": "Pebrel is running from a temporary macOS location. Move the app to a trusted folder and reopen it.",
+      "write_failed": "Could not use the portable data folder {path}: {error}",
+      "linked_directory": "The portable data folder or its temporary folder is a symbolic link.",
+      "error_title": "Pebrel could not start"
+    }
+  },
   "theme": {
     "package": {
       "entry": "Theme package",

nebula_app/i18n/zh-CN.json

@@ -1263,6 +1263,19 @@
     "relay_invalid": "配置格式有误。请导入 pebrel-relay 导出的连接信息，或补全地址、房间号、令牌和指纹。",
     "relay_read_failed": "读取未完成。请检查 SSH 主机连接，以及服务器是否已安装 pebrel-relay。"
   },
+  "startup": {
+    "portable": {
+      "title": "便携模式",
+      "description": "Pebrel 位于“应用程序”文件夹之外。是否将数据保存在应用旁的 {path}？",
+      "enable": "使用便携模式",
+      "normal": "使用普通模式",
+      "quit": "退出",
+      "translocated": "Pebrel 正在从 macOS 临时转译位置运行。请将应用移到可信文件夹后重新打开。",
+      "write_failed": "无法使用便携数据文件夹 {path}：{error}",
+      "linked_directory": "便携数据文件夹或其临时文件夹是符号链接。",
+      "error_title": "Pebrel 无法启动"
+    }
+  },
   "theme": {
     "package": {
       "entry": "主题包",

nebula_app/src/main.rs

@@ -199,9 +199,24 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     // Load command line options.
     let options = Options::new();
-    if let Err(error) = nebula_settings::migrate_legacy_data() {
-        platform::startup::report_error(&error, options.subcommands.is_none());
-        return Err(error.into());
+    let startup = platform::startup::prepare_data(&options).and_then(|launch| {
+        use platform::startup::Launch;
+        match launch {
+            Launch::Installed => nebula_settings::migrate_legacy_data().map(|_| true),
+            Launch::Portable => Ok(true),
+            Launch::Quit => Ok(false),
+        }
+    });
+    match startup {
+        Ok(true) => {},
+        Ok(false) => return Ok(()),
+        Err(error) => {
+            platform::startup::report_error(
+                &error,
+                options.subcommands.is_none() && !options.daemon,
+            );
+            return Err(error.into());
+        },
     }
     #[cfg(windows)]
     panic::attach_handler();