Add isolated Hive store launch flag

README.md

@@ -40,6 +40,31 @@ flutter pub get
 flutter run
 ```
 
+### Isolated Hive store
+
+Desktop builds accept an absolute `--hive-store-dir` path. It moves every
+Hive box, including the library, preferences, and anonymous analytics, without
+touching the normal Hive files.
+
+Pass the option through Flutter with one Dart entrypoint argument:
+
+```bash
+fvm flutter run -d macos -a "--hive-store-dir=/Users/your-name/Library/Containers/xyz.icarus-strats/Data/Library/Application Support/xyz.icarus-strats-demo"
+```
+
+The macOS app sandbox limits this path to Icarus's container unless the user
+selects another directory through a native picker. The container lives at
+`~/Library/Containers/xyz.icarus-strats/Data`.
+
+Or pass it directly to a built executable:
+
+```bash
+./icarus --hive-store-dir "/absolute/path/to/icarus-demo-hive"
+```
+
+Strategy media, debug logs, and WebView data still use the normal application
+support directory. Use a different absolute Hive directory for each instance.
+
 ## Build
 
 ```bash

lib/main.dart

@@ -30,6 +30,8 @@ import 'package:icarus/providers/strategy_provider.dart';
 import 'package:icarus/services/app_error_reporter.dart';
 import 'package:icarus/services/analytics_service.dart';
 import 'package:icarus/services/discord_presence_service.dart';
+import 'package:icarus/startup/hive_store_launch.dart';
+import 'package:icarus/startup/windows_process_termination.dart';
 import 'package:icarus/strategy_view.dart';
 import 'package:icarus/widgets/folder_navigator.dart';
 import 'package:icarus/widgets/global_shortcuts.dart';
@@ -52,24 +54,43 @@ Future<void> main(List<String> args) async {
       await _initializePersistedDebugLog();
       _installGlobalErrorHandlers();
 
+      final launch = HiveStoreLaunch.parse(args);
+      final PreparedHiveStore? alternateHiveStore;
+      if (kIsWeb) {
+        launch.validateForWeb();
+        alternateHiveStore = null;
+      } else {
+        alternateHiveStore = await launch.prepareAlternateStore(
+          getDefaultHiveDirectory: getApplicationSupportDirectory,
+        );
+      }
+
       if (!kIsWeb && Platform.isWindows) {
         await WindowsSingleInstance.ensureSingleInstance(
-          args,
-          'icarus_single_instance',
+          launch.fileOpenArgs,
+          alternateHiveStore?.windowsSingleInstanceId ??
+              HiveStoreLaunch.defaultWindowsSingleInstanceId,
           onSecondWindow: (args) {
             publishSecondInstanceArgs(args);
           },
+          exitFunction: terminateDuplicateWindowsProcess,
         );
       }
 
       if (kIsWeb) {
         // On web, Hive uses IndexedDB; no path needed.
         await Hive.initFlutter();
       } else {
-        // On mobile/desktop, you can still choose an explicit directory.
-        final dir = await getApplicationSupportDirectory();
+        final hiveDirectoryPath = alternateHiveStore?.hiveDirectoryPath ??
+            (await getApplicationSupportDirectory()).path;
         await getTemporaryDirectory();
-        await Hive.initFlutter(dir.path);
+        await Hive.initFlutter(hiveDirectoryPath);
+        if (alternateHiveStore != null) {
+          AppErrorReporter.reportInfo(
+            'Using alternate Hive store: $hiveDirectoryPath',
+            source: 'main.hiveStore',
+          );
+        }
       }
 
       staticDrawingCursor = await CustomMouseCursor.icon(
@@ -126,7 +147,7 @@ Future<void> main(List<String> args) async {
       runApp(
         UncontrolledProviderScope(
           container: appProviderContainer,
-          child: MyApp(data: args),
+          child: MyApp(data: launch.fileOpenArgs),
         ),
       );
     },

lib/startup/hive_store_launch.dart

@@ -0,0 +1,182 @@
+import 'dart:convert';
+import 'dart:io';
+
+import 'package:cryptography_plus/cryptography_plus.dart';
+import 'package:path/path.dart' as path;
+
+final class HiveStoreLaunchException implements Exception {
+  const HiveStoreLaunchException(this.message, [this.cause]);
+
+  final String message;
+  final Object? cause;
+
+  @override
+  String toString() => message;
+}
+
+final class HiveStoreLaunch {
+  const HiveStoreLaunch._({
+    required this.fileOpenArgs,
+    required String? alternateHiveDirectory,
+  }) : _alternateHiveDirectory = alternateHiveDirectory;
+
+  static const optionName = '--hive-store-dir';
+  static const defaultWindowsSingleInstanceId = 'icarus_single_instance';
+
+  final List<String> fileOpenArgs;
+  final String? _alternateHiveDirectory;
+
+  static HiveStoreLaunch parse(List<String> rawArgs) {
+    final fileOpenArgs = <String>[];
+    String? alternateHiveDirectory;
+    var sawOption = false;
+
+    for (var index = 0; index < rawArgs.length; index += 1) {
+      final argument = rawArgs[index];
+      if (argument == optionName) {
+        if (sawOption) {
+          throw const HiveStoreLaunchException(
+            '$optionName may only be supplied once.',
+          );
+        }
+        if (index + 1 >= rawArgs.length ||
+            rawArgs[index + 1] == optionName ||
+            rawArgs[index + 1].startsWith('$optionName=')) {
+          throw const HiveStoreLaunchException(
+            '$optionName requires an absolute directory path.',
+          );
+        }
+        sawOption = true;
+        alternateHiveDirectory = rawArgs[++index];
+        _validateOptionValue(alternateHiveDirectory);
+        continue;
+      }
+
+      if (argument.startsWith('$optionName=')) {
+        if (sawOption) {
+          throw const HiveStoreLaunchException(
+            '$optionName may only be supplied once.',
+          );
+        }
+        sawOption = true;
+        alternateHiveDirectory = argument.substring(optionName.length + 1);
+        _validateOptionValue(alternateHiveDirectory);
+        continue;
+      }
+
+      fileOpenArgs.add(argument);
+    }
+
+    return HiveStoreLaunch._(
+      fileOpenArgs: List.unmodifiable(fileOpenArgs),
+      alternateHiveDirectory: alternateHiveDirectory,
+    );
+  }
+
+  void validateForWeb() {
+    if (_alternateHiveDirectory == null) return;
+    throw const HiveStoreLaunchException(
+      '$optionName is only available in desktop builds.',
+    );
+  }
+
+  Future<PreparedHiveStore?> prepareAlternateStore({
+    required Future<Directory> Function() getDefaultHiveDirectory,
+    Future<void> Function(Directory directory)? probeDirectory,
+  }) async {
+    final requestedPath = _alternateHiveDirectory;
+    if (requestedPath == null) return null;
+    if (!path.isAbsolute(requestedPath)) {
+      throw HiveStoreLaunchException(
+        '$optionName requires an absolute path: $requestedPath',
+      );
+    }
+
+    try {
+      final requestedDirectory = Directory(path.normalize(requestedPath));
+      await requestedDirectory.create(recursive: true);
+      final canonicalPath = path.normalize(
+        await requestedDirectory.resolveSymbolicLinks(),
+      );
+      final canonicalDirectory = Directory(canonicalPath);
+      await (probeDirectory ?? _probeDirectory)(canonicalDirectory);
+
+      final defaultDirectory = await getDefaultHiveDirectory();
+      final defaultPath = await _resolvedDirectoryPath(defaultDirectory);
+      final isDefaultDirectory =
+          _pathIdentity(canonicalPath) == _pathIdentity(defaultPath);
+
+      return PreparedHiveStore(
+        hiveDirectoryPath: canonicalPath,
+        windowsSingleInstanceId: isDefaultDirectory
+            ? defaultWindowsSingleInstanceId
+            : await _windowsSingleInstanceId(canonicalPath),
+      );
+    } on HiveStoreLaunchException {
+      rethrow;
+    } catch (error) {
+      throw HiveStoreLaunchException(
+        'Could not prepare Hive store directory: $requestedPath',
+        error,
+      );
+    }
+  }
+
+  static void _validateOptionValue(String value) {
+    if (value.isEmpty) {
+      throw const HiveStoreLaunchException(
+        '$optionName requires a non-empty directory path.',
+      );
+    }
+    if (value.contains('\u0000')) {
+      throw const HiveStoreLaunchException(
+        '$optionName cannot contain a NUL character.',
+      );
+    }
+  }
+
+  static Future<void> _probeDirectory(Directory directory) async {
+    final probeDirectory = await directory.createTemp('.icarus-hive-probe-');
+    try {
+      final probeFile = File(path.join(probeDirectory.path, 'write-probe'));
+      await probeFile.writeAsBytes(const [0], flush: true);
+    } finally {
+      if (await probeDirectory.exists()) {
+        await probeDirectory.delete(recursive: true);
+      }
+    }
+  }
+
+  static Future<String> _resolvedDirectoryPath(Directory directory) async {
+    final absoluteDirectory =
+        Directory(path.normalize(directory.absolute.path));
+    if (!await absoluteDirectory.exists()) return absoluteDirectory.path;
+    return path.normalize(await absoluteDirectory.resolveSymbolicLinks());
+  }
+
+  static String _pathIdentity(String directoryPath) {
+    final normalized = path.normalize(directoryPath);
+    return Platform.isWindows ? normalized.toLowerCase() : normalized;
+  }
+
+  static Future<String> _windowsSingleInstanceId(
+    String canonicalPath,
+  ) async {
+    final digest =
+        await Sha256().hash(utf8.encode(_pathIdentity(canonicalPath)));
+    final hex = digest.bytes
+        .map((byte) => byte.toRadixString(16).padLeft(2, '0'))
+        .join();
+    return '${defaultWindowsSingleInstanceId}_$hex';
+  }
+}
+
+final class PreparedHiveStore {
+  const PreparedHiveStore({
+    required this.hiveDirectoryPath,
+    required this.windowsSingleInstanceId,
+  });
+
+  final String hiveDirectoryPath;
+  final String windowsSingleInstanceId;
+}

lib/startup/windows_process_termination.dart

@@ -0,0 +1,2 @@
+export 'windows_process_termination_stub.dart'
+    if (dart.library.io) 'windows_process_termination_io.dart';

lib/startup/windows_process_termination_io.dart

@@ -0,0 +1,22 @@
+import 'dart:async';
+import 'dart:io';
+
+import 'package:win32/win32.dart';
+
+Future<void> terminateDuplicateWindowsProcess() {
+  if (!Platform.isWindows) {
+    throw UnsupportedError('Windows process termination requires Windows.');
+  }
+
+  // flutter_inappwebview_windows can crash in DLL_PROCESS_DETACH while
+  // releasing static WinRT state. This runs after argument forwarding and
+  // before Hive opens, so skipping DLL cleanup cannot interrupt library writes.
+  // See https://github.com/pichillilorenzo/flutter_inappwebview/issues/2733.
+  final result = TerminateProcess(GetCurrentProcess(), 0);
+  if (result == 0) {
+    throw WindowsException(HRESULT_FROM_WIN32(GetLastError()));
+  }
+
+  // Keep startup suspended until Windows finishes terminating the process.
+  return Completer<void>().future;
+}

lib/startup/windows_process_termination_stub.dart

@@ -0,0 +1,3 @@
+Future<void> terminateDuplicateWindowsProcess() async {
+  throw UnsupportedError('Windows process termination requires Windows.');
+}

pubspec.lock

@@ -1337,7 +1337,7 @@ packages:
     source: hosted
     version: "3.1.0"
   win32:
-    dependency: transitive
+    dependency: "direct main"
     description:
       name: win32
       sha256: d7cb55e04cd34096cd3a79b3330245f54cb96a370a1c27adb3c84b917de8b08e

pubspec.yaml

@@ -38,6 +38,7 @@ dependencies:
   custom_mouse_cursor: ^1.1.3
   flutter_inappwebview: ^6.1.5
   windows_single_instance: ^1.0.0
+  win32: ^5.15.0
   pasteboard: ^0.4.0
   desktop_updater: ^1.4.0
   cryptography_plus: ^2.7.1