feat: Implement deep link support + refactored oauth to use it (#260)

Implement deep link support + refactored oauth to use deep linking in production

On macOS and Linux, the deep link feature will only work when the app is packaged and moved to Applications. It will not work when launching it in development from the command-line, so for development purposes I kept HTTP server oauth for when Array is started using the dev server.

PostHog/posthog#43349

Author: charlesvien

apps/array/package.json

@@ -13,6 +13,7 @@
     "dev": "electron-forge start",
     "start": "electron-forge start",
     "package": "electron-forge package",
+    "package:dev": "FORCE_DEV_MODE=1 SKIP_NOTARIZE=1 electron-forge package",
     "make": "electron-forge make",
     "publish": "electron-forge publish",
     "build": "pnpm package",

apps/array/src/constants/oauth.ts

@@ -4,8 +4,6 @@ export const POSTHOG_US_CLIENT_ID = "HCWoE0aRFMYxIxFNTTwkOORn5LBjOt2GVDzwSw5W";
 export const POSTHOG_EU_CLIENT_ID = "AIvijgMS0dxKEmr5z6odvRd8Pkh5vts3nPTzgzU9";
 export const POSTHOG_DEV_CLIENT_ID = "DC5uRLVbGI02YQ82grxgnK6Qn12SXWpCqdPb60oZ";
 
-export const OAUTH_PORT = 8237;
-
 export const OAUTH_SCOPES = [
   // Array app needs
   "user:read",

apps/array/src/main/di/container.ts

@@ -1,6 +1,7 @@
 import "reflect-metadata";
 import { Container } from "inversify";
 import { ContextMenuService } from "../services/context-menu/service.js";
+import { DeepLinkService } from "../services/deep-link/service.js";
 import { DockBadgeService } from "../services/dock-badge/service.js";
 import { ExternalAppsService } from "../services/external-apps/service.js";
 import { FileWatcherService } from "../services/file-watcher/service.js";
@@ -17,6 +18,7 @@ export const container = new Container({
 });
 
 container.bind(MAIN_TOKENS.ContextMenuService).to(ContextMenuService);
+container.bind(MAIN_TOKENS.DeepLinkService).to(DeepLinkService);
 container.bind(MAIN_TOKENS.DockBadgeService).to(DockBadgeService);
 container.bind(MAIN_TOKENS.ExternalAppsService).to(ExternalAppsService);
 container.bind(MAIN_TOKENS.FileWatcherService).to(FileWatcherService);

apps/array/src/main/di/tokens.ts

@@ -13,6 +13,7 @@ export const MAIN_TOKENS = Object.freeze({
   FoldersService: Symbol.for("Main.FoldersService"),
   FsService: Symbol.for("Main.FsService"),
   GitService: Symbol.for("Main.GitService"),
+  DeepLinkService: Symbol.for("Main.DeepLinkService"),
   OAuthService: Symbol.for("Main.OAuthService"),
   ShellService: Symbol.for("Main.ShellService"),
   UpdatesService: Symbol.for("Main.UpdatesService"),

apps/array/src/main/index.ts

@@ -35,7 +35,9 @@ type TaskController = unknown;
 
 import { registerGitIpc } from "./services/git.js";
 import "./services/index.js";
-import { ExternalAppsService } from "./services/external-apps/service.js";
+import type { DeepLinkService } from "./services/deep-link/service.js";
+import type { ExternalAppsService } from "./services/external-apps/service.js";
+import type { OAuthService } from "./services/oauth/service.js";
 import {
   initializePostHog,
   shutdownPostHog,
@@ -60,6 +62,58 @@ dns.setDefaultResultOrder("ipv4first");
 // Set app name to ensure consistent userData path across platforms
 app.setName("Array");
 
+// Single instance lock must be acquired FIRST before any other app setup
+// This ensures deep links go to the existing instance, not a new one
+// In development, we need to pass the same args that setAsDefaultProtocolClient uses
+const additionalData = process.defaultApp ? { argv: process.argv } : undefined;
+const gotTheLock = app.requestSingleInstanceLock(additionalData);
+if (!gotTheLock) {
+  app.quit();
+  // Must exit immediately to prevent any further initialization
+  process.exit(0);
+}
+
+// Queue to hold deep link URLs received before app is ready
+let pendingDeepLinkUrl: string | null = null;
+
+// Handle deep link URLs on macOS - must be registered before app is ready
+app.on("open-url", (event, url) => {
+  event.preventDefault();
+
+  // If the app isn't ready yet, queue the URL for later processing
+  if (!app.isReady()) {
+    pendingDeepLinkUrl = url;
+    return;
+  }
+
+  const deepLinkService = container.get<DeepLinkService>(
+    MAIN_TOKENS.DeepLinkService,
+  );
+  deepLinkService.handleUrl(url);
+
+  // Focus the main window when receiving a deep link
+  if (mainWindow) {
+    if (mainWindow.isMinimized()) mainWindow.restore();
+    mainWindow.focus();
+  }
+});
+
+// Handle deep link URLs on Windows/Linux (second instance sends URL via command line)
+app.on("second-instance", (_event, commandLine) => {
+  const url = commandLine.find((arg) => arg.startsWith("array://"));
+  if (url) {
+    const deepLinkService = container.get<DeepLinkService>(
+      MAIN_TOKENS.DeepLinkService,
+    );
+    deepLinkService.handleUrl(url);
+  }
+
+  if (mainWindow) {
+    if (mainWindow.isMinimized()) mainWindow.restore();
+    mainWindow.focus();
+  }
+});
+
 function ensureClaudeConfigDir(): void {
   const existing = process.env.CLAUDE_CONFIG_DIR;
   if (existing) return;
@@ -256,6 +310,15 @@ app.whenReady().then(() => {
   createWindow();
   ensureClaudeConfigDir();
 
+  // Initialize deep link service and register protocol
+  const deepLinkService = container.get<DeepLinkService>(
+    MAIN_TOKENS.DeepLinkService,
+  );
+  deepLinkService.registerProtocol();
+
+  // Initialize OAuth service (registers its deep link handler)
+  container.get<OAuthService>(MAIN_TOKENS.OAuthService);
+
   // Initialize services that need early startup
   container.get<DockBadgeService>(MAIN_TOKENS.DockBadgeService);
   container.get<UpdatesService>(MAIN_TOKENS.UpdatesService);
@@ -265,9 +328,22 @@ app.whenReady().then(() => {
   trackAppEvent(ANALYTICS_EVENTS.APP_STARTED);
 
   // Preload external app icons in background
-  new ExternalAppsService().getDetectedApps().catch(() => {
-    // Silently fail, will retry on first use
-  });
+  container.get<ExternalAppsService>(MAIN_TOKENS.ExternalAppsService);
+
+  // Handle case where app was launched by a deep link
+  if (process.platform === "darwin") {
+    // On macOS, the open-url event may have fired before app was ready
+    if (pendingDeepLinkUrl) {
+      deepLinkService.handleUrl(pendingDeepLinkUrl);
+      pendingDeepLinkUrl = null;
+    }
+  } else {
+    // On Windows/Linux, the URL comes via command line arguments
+    const deepLinkUrl = process.argv.find((arg) => arg.startsWith("array://"));
+    if (deepLinkUrl) {
+      deepLinkService.handleUrl(deepLinkUrl);
+    }
+  }
 });
 
 app.on("window-all-closed", async () => {

apps/array/src/main/services/deep-link/service.ts

@@ -0,0 +1,111 @@
+import { app } from "electron";
+import { injectable } from "inversify";
+import { logger } from "../../lib/logger.js";
+
+const log = logger.scope("deep-link-service");
+
+const PROTOCOL = "array";
+
+export type DeepLinkHandler = (url: URL) => boolean;
+
+@injectable()
+export class DeepLinkService {
+  private protocolRegistered = false;
+  private handlers = new Map<string, DeepLinkHandler>();
+
+  /**
+   * Register the app as the default handler for the 'array' protocol.
+   * Should be called once during app initialization (in whenReady).
+   */
+  public registerProtocol(): void {
+    if (this.protocolRegistered) {
+      return;
+    }
+
+    // Register the protocol
+    if (process.defaultApp) {
+      // Development: need to register with path to electron
+      if (process.argv.length >= 2) {
+        app.setAsDefaultProtocolClient(PROTOCOL, process.execPath, [
+          process.argv[1],
+        ]);
+      }
+    } else {
+      // Production
+      app.setAsDefaultProtocolClient(PROTOCOL);
+    }
+
+    this.protocolRegistered = true;
+    log.info(`Registered '${PROTOCOL}' protocol handler`);
+  }
+
+  /**
+   * Register a handler for a specific deep link path.
+   * @param path The path to handle (e.g., "callback", "task", "settings")
+   * @param handler Function that receives the parsed URL and returns true if handled
+   */
+  public registerHandler(path: string, handler: DeepLinkHandler): void {
+    if (this.handlers.has(path)) {
+      log.warn(`Overwriting existing handler for path: ${path}`);
+    }
+    this.handlers.set(path, handler);
+    log.info(`Registered deep link handler for path: ${path}`);
+  }
+
+  /**
+   * Unregister a handler for a specific path.
+   */
+  public unregisterHandler(path: string): void {
+    this.handlers.delete(path);
+  }
+
+  /**
+   * Handle an incoming deep link URL.
+   * Routes to the appropriate registered handler based on the URL path.
+   * @returns true if the URL was handled, false otherwise
+   */
+  public handleUrl(url: string): boolean {
+    log.info("Received deep link:", url);
+
+    if (!url.startsWith(`${PROTOCOL}://`)) {
+      log.warn("URL does not match protocol:", url);
+      return false;
+    }
+
+    try {
+      const parsedUrl = new URL(url);
+
+      // The "path" can be the hostname (array://callback) or pathname (array://foo/callback)
+      // For simple paths like array://callback, hostname is "callback" and pathname is "/"
+      // For paths like array://oauth/callback, hostname is "oauth" and pathname is "/callback"
+      const path = parsedUrl.hostname || parsedUrl.pathname.slice(1);
+
+      const handler = this.handlers.get(path);
+      if (handler) {
+        return handler(parsedUrl);
+      }
+
+      // Try matching with pathname for nested paths like array://oauth/callback
+      if (parsedUrl.pathname !== "/") {
+        const fullPath = `${parsedUrl.hostname}${parsedUrl.pathname}`;
+        const nestedHandler = this.handlers.get(fullPath);
+        if (nestedHandler) {
+          return nestedHandler(parsedUrl);
+        }
+      }
+
+      log.warn("No handler registered for deep link path:", path);
+      return false;
+    } catch (error) {
+      log.error("Failed to parse deep link URL:", error);
+      return false;
+    }
+  }
+
+  /**
+   * Get the protocol name.
+   */
+  public getProtocol(): string {
+    return PROTOCOL;
+  }
+}