feat(web): guide the user to Full Disk Access when Safari import is blocked

Safari's cookies sit behind Full Disk Access, and macOS never prompts for it —
the app is added by hand — so a toast naming the setting left the user to hunt
for it. An import that fails with `needsFullDiskAccess` now opens a dialog that
explains why and links straight into System Settings → Privacy & Security →
Full Disk Access.

Every other failure keeps its toast. `importFailureReason` is exported and
tested, since the whole path depends on the reason token surviving the trip
through IPC.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: juliusmarminge

apps/web/src/components/settings/IntegrationsSettings.logic.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { importFailureReason } from "./IntegrationsSettings";
+
+// Mirrors `BrowserImportFailedError.message`, which IPC flattens to a string
+// before the renderer sees it.
+const failure = (reason: string) => ({
+  message: `Importing cookies from safari failed: ${reason}.`,
+});
+
+describe("importFailureReason", () => {
+  it("recovers the reason token from the flattened message", () => {
+    // The whole import error path — including the Full Disk Access dialog —
+    // depends on this token surviving the trip through IPC.
+    expect(importFailureReason(failure("needsFullDiskAccess"))).toBe("needsFullDiskAccess");
+    expect(importFailureReason(failure("browserRunning"))).toBe("browserRunning");
+    expect(importFailureReason(failure("readFailed"))).toBe("readFailed");
+  });
+
+  it("falls back to readFailed for anything it cannot classify", () => {
+    expect(importFailureReason(new Error("something else entirely"))).toBe("readFailed");
+    expect(importFailureReason(undefined)).toBe("readFailed");
+  });
+});

apps/web/src/components/settings/IntegrationsSettings.tsx

@@ -54,6 +54,8 @@ import {
   MenuSubTrigger,
   MenuTrigger,
 } from "../ui/menu";
+import { readLocalApi } from "~/localApi";
+
 import { toastManager } from "../ui/toast";
 import {
   AlertDialog,
@@ -117,7 +119,7 @@ const zoomLabel = (zoomFactor: number) => `${Math.round(zoomFactor * 100)}%`;
  * it. Anything unrecognised reads as a plain read failure rather than leaking
  * the raw message into a toast.
  */
-const importFailureReason = (cause: unknown): BrowserImportFailureReason => {
+export const importFailureReason = (cause: unknown): BrowserImportFailureReason => {
   const message = String((cause as { message?: unknown } | undefined)?.message ?? "");
   return (
     BrowserImportFailureReason.literals.find((reason) => message.includes(`failed: ${reason}.`)) ??
@@ -520,13 +522,25 @@ function DesktopOnlyBrowserDefaults({ children }: { readonly children: ReactNode
  * files, and the answer changes while the app is running (quitting the browser
  * clears `browserRunning`), so a value cached at mount would go stale.
  */
+/**
+ * Opens System Settings → Privacy & Security → Full Disk Access. The scheme is
+ * unchanged from the old System Preferences and still resolves on Ventura and
+ * later.
+ */
+const FULL_DISK_ACCESS_SETTINGS_URL =
+  "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFilesAccess";
+
 function BrowserProfilesSetting({ disabled }: { readonly disabled: boolean }) {
   const userProfiles = useClientSettings((settings) => settings.browserProfiles);
   const defaultProfileId = useClientSettings((settings) => settings.browserDefaultProfileId);
   const updateSettings = useUpdatePrimarySettings();
   const environmentId = usePrimaryEnvironment()?.environmentId;
   const [sources, setSources] = useState<ReadonlyArray<BrowserImportSource> | null>(null);
   const [busy, setBusy] = useState(false);
+  // Safari's cookies sit behind Full Disk Access, which macOS never prompts
+  // for — the app is added by hand. A dialog with a link into the right pane
+  // is more use than a toast that names a setting the user then has to find.
+  const [fullDiskAccessSource, setFullDiskAccessSource] = useState<string | null>(null);
   const [profilePendingRemoval, setProfilePendingRemoval] = useState<BrowserProfile | null>(null);
 
   const profiles = resolveBrowserProfiles(userProfiles);
@@ -653,10 +667,15 @@ function BrowserProfilesSetting({ disabled }: { readonly disabled: boolean }) {
         });
       })
       .catch((cause: unknown) => {
+        const reason = importFailureReason(cause);
+        if (reason === "needsFullDiskAccess") {
+          setFullDiskAccessSource(source.name);
+          return;
+        }
         toastManager.add({
           type: "error",
           title: `Could not import from ${source.name}`,
-          description: BROWSER_IMPORT_FAILURE_COPY[importFailureReason(cause)],
+          description: BROWSER_IMPORT_FAILURE_COPY[reason],
         });
       })
       .finally(() => setBusy(false));
@@ -882,6 +901,36 @@ function BrowserProfilesSetting({ disabled }: { readonly disabled: boolean }) {
           </AlertDialogFooter>
         </AlertDialogPopup>
       </AlertDialog>
+      <AlertDialog
+        open={fullDiskAccessSource !== null}
+        onOpenChange={(open) => {
+          if (!open) setFullDiskAccessSource(null);
+        }}
+      >
+        <AlertDialogPopup>
+          <AlertDialogHeader>
+            <AlertDialogTitle>T3 Code needs Full Disk Access</AlertDialogTitle>
+            <AlertDialogDescription>
+              {fullDiskAccessSource ?? "Safari"} keeps its cookies in a protected folder. Turn on
+              Full Disk Access for T3 Code in System Settings, then run the import again. macOS
+              doesn’t ask for this permission — you add the app yourself.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogClose render={<Button variant="outline" />}>Not now</AlertDialogClose>
+            <AlertDialogClose
+              render={<Button />}
+              onClick={() => {
+                void readLocalApi()
+                  ?.shell.openExternal(FULL_DISK_ACCESS_SETTINGS_URL)
+                  .catch(() => undefined);
+              }}
+            >
+              Open System Settings
+            </AlertDialogClose>
+          </AlertDialogFooter>
+        </AlertDialogPopup>
+      </AlertDialog>
     </SettingsRow>
   );
 }