fix(desktop): queue early macOS deep links to prevent auth redirect loss

[Kitenite]

Summary

• Fixes auth redirect going to the Electron binary welcome page instead of the running app instance
• Queues open-url events that fire before the window is ready (macOS cold-start via protocol link) and processes them after initialization
• Cleans up redundant comments throughout the entry point

Test plan

• Sign in via OAuth with the app already running — callback should focus the existing window
• Sign in via OAuth with the app closed — macOS launches the app and the queued auth callback completes after initialization
• Deep link navigation (e.g. superset://tasks/slug) works in both scenarios

Summary by CodeRabbit

• Bug Fixes
  • Improved handling of deep-links and protocol URLs passed to the application
  • Enhanced reliability of app startup when receiving protocol links during initialization
  • Better queue management for application links received before full app launch

[coderabbitai]

📝 Walkthrough

Walkthrough

Refactored the main Electron app initialization and deep-link handling to defer processing until after app readiness, introduce queuing for open-url events, and simplify quit confirmation logic. Enhanced dev-mode parent-process monitoring and consolidated renderer communication.

Changes

Cohort / File(s)	Summary
Main process initialization & deep-link handling apps/desktop/src/main/index.ts	Introduced appReady state flow to queue and process deep links after app initialization. Refactored protocol client setup for dev-mode, improved quit confirmation with early return on user cancellation, and updated parent-process monitoring in development mode with isParentAlive replacement. Added Windows/Linux-specific second-instance protocol URL handling.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• fix(desktop): ensure Electron quits when dev server stops #888 — Modifies desktop main process termination logic and development parent-process monitoring, including app.exit(0) usage and dev-mode exit patterns.

Poem

🐰 Deep links now queue with patient grace,
As apps await their ready state.
The main process hops with cleaner pace,
Dev-mode exit sealed by fate. ✨

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description includes a summary of changes and test plan, but is missing required template sections such as Related Issues, Type of Change, and Additional Notes.	Add the missing template sections: Related Issues (if any), Type of Change (mark 'Bug fix' as applicable), and optionally fill in Additional Notes for more context.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main fix: queuing early macOS deep links to prevent auth redirect loss, which aligns with the primary objective of the changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch kitenite/entrypoint

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

apps/desktop/src/main/index.ts (2)

54-62: path variable shadows the path module import from line 1.

const path on line 56 shadows the node:path import. This won't cause a runtime bug today since path.resolve (line 33) is called earlier, but it's a maintenance hazard — any future use of the path module after this point in the function would silently reference the string instead.

Also, url.split("://")[1] is fragile for URLs with query strings or fragments. Consider using new URL(url) for proper parsing.

Proposed fix

-	// Non-auth deep links: extract path and navigate in renderer
-	// e.g. superset://tasks/my-slug -> /tasks/my-slug
-	const path = `/${url.split("://")[1]}`;
+	// Non-auth deep links: extract path and navigate in renderer
+	// e.g. superset://tasks/my-slug -> /tasks/my-slug
+	const parsed = new URL(url);
+	const deepLinkPath = `${parsed.pathname}${parsed.search}${parsed.hash}`;

And update the send call accordingly:

-		windows[0].webContents.send("deep-link-navigate", path);
+		windows[0].webContents.send("deep-link-navigate", deepLinkPath);

---

249-259: Potential double-processing if both argv and open-url carry the same deep link.

On macOS cold start, the URL typically arrives only via open-url (queued in pendingDeepLinkUrl). On Windows/Linux, it arrives via argv. So in practice these shouldn't overlap. However, if a platform ever delivers both, processDeepLink would run twice for the same URL.

A lightweight guard would prevent this:

Proposed guard

 		// Process any deep links from cold start
 		const coldStartUrl = findDeepLinkInArgv(process.argv);
 		if (coldStartUrl) {
 			await processDeepLink(coldStartUrl);
+			// Clear pending if it's the same URL to avoid double-processing
+			if (pendingDeepLinkUrl === coldStartUrl) {
+				pendingDeepLinkUrl = null;
+			}
 		}
 		if (pendingDeepLinkUrl) {

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🧹 Preview Cleanup Complete

The following preview resources have been cleaned up:

• ⚠️ Neon database branch
• ⚠️ Electric Fly.io app
• ⚠️ Streams Fly.io app

Thank you for your contribution! 🎉