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

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,8 @@
 import "reflect-metadata";
 import { Container } from "inversify";
+import { DeepLinkService } from "../services/deep-link/service.js";
 import { GitService } from "../services/git/service.js";
+import { OAuthService } from "../services/oauth/service.js";
 import { MAIN_TOKENS } from "./tokens.js";
 
 /**
@@ -12,6 +14,10 @@ export const container = new Container({
 
 // Bind services
 container.bind<GitService>(MAIN_TOKENS.GitService).to(GitService);
+container
+  .bind<DeepLinkService>(MAIN_TOKENS.DeepLinkService)
+  .to(DeepLinkService);
+container.bind<OAuthService>(MAIN_TOKENS.OAuthService).to(OAuthService);
 
 export function get<T>(token: symbol): T {
   return container.get<T>(token);

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

@@ -7,4 +7,6 @@
 export const MAIN_TOKENS = Object.freeze({
   // Services
   GitService: Symbol.for("Main.GitService"),
+  DeepLinkService: Symbol.for("Main.DeepLinkService"),
+  OAuthService: Symbol.for("Main.OAuthService"),
 });

apps/array/src/main/index.ts

@@ -14,7 +14,11 @@ import {
 import { createIPCHandler } from "trpc-electron/main";
 import "./lib/logger";
 import { ANALYTICS_EVENTS } from "../types/analytics.js";
+import { get } from "./di/container.js";
+import { MAIN_TOKENS } from "./di/tokens.js";
+import type { DeepLinkService } from "./services/deep-link/service.js";
 import { dockBadgeService } from "./services/dockBadge.js";
+import type { OAuthService } from "./services/oauth/service.js";
 import {
   cleanupAgentSessions,
   registerAgentIpc,
@@ -34,7 +38,6 @@ import {
   getOrRefreshApps,
   registerExternalAppsIpc,
 } from "./services/externalApps.js";
-import { registerOAuthHandlers } from "./services/oauth.js";
 import {
   initializePostHog,
   shutdownPostHog,
@@ -61,6 +64,54 @@ 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 = 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 = 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;
@@ -219,6 +270,17 @@ app.whenReady().then(() => {
   createWindow();
   ensureClaudeConfigDir();
 
+  // Initialize deep link service and register protocol
+  const deepLinkService = get<DeepLinkService>(MAIN_TOKENS.DeepLinkService);
+  deepLinkService.registerProtocol();
+
+  // Register OAuth callback handler for deep links
+  const oauthService = get<OAuthService>(MAIN_TOKENS.OAuthService);
+  deepLinkService.registerHandler(
+    "callback",
+    oauthService.getDeepLinkHandler(),
+  );
+
   // Initialize dock badge service for notification badges
   dockBadgeService.initialize(() => mainWindow);
 
@@ -230,6 +292,21 @@ app.whenReady().then(() => {
   getOrRefreshApps().catch(() => {
     // Silently fail, will retry on first use
   });
+
+  // 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 () => {
@@ -260,7 +337,6 @@ registerAutoUpdater(() => mainWindow);
 ipcMain.handle("app:get-version", () => app.getVersion());
 
 // Register IPC handlers via services
-registerOAuthHandlers();
 registerGitIpc();
 registerAgentIpc(taskControllers, () => mainWindow);
 registerFsIpc();

apps/array/src/main/preload.ts

@@ -10,7 +10,6 @@ import type {
   WorkspaceTerminalInfo,
   WorktreeInfo,
 } from "../shared/types";
-import type { CloudRegion, OAuthTokenResponse } from "../shared/types/oauth";
 import type {
   ExternalAppContextMenuResult,
   FolderContextMenuResult,
@@ -61,18 +60,6 @@ interface AgentStartParams {
 }
 
 contextBridge.exposeInMainWorld("electronAPI", {
-  // OAuth API
-  oauthStartFlow: (
-    region: CloudRegion,
-  ): Promise<{ success: boolean; data?: OAuthTokenResponse; error?: string }> =>
-    ipcRenderer.invoke("oauth:start-flow", region),
-  oauthRefreshToken: (
-    refreshToken: string,
-    region: CloudRegion,
-  ): Promise<{ success: boolean; data?: OAuthTokenResponse; error?: string }> =>
-    ipcRenderer.invoke("oauth:refresh-token", refreshToken, region),
-  oauthCancelFlow: (): Promise<{ success: boolean; error?: string }> =>
-    ipcRenderer.invoke("oauth:cancel-flow"),
   // Repo API
   validateRepo: (directoryPath: string): Promise<boolean> =>
     ipcRenderer.invoke("validate-repo", directoryPath),

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;
+  }
+}

apps/array/src/main/services/index.ts

@@ -10,7 +10,6 @@ import "./fileWatcher.js";
 import "./folders.js";
 import "./fs.js";
 import "./git.js";
-import "./oauth.js";
 import "./posthog-analytics.js";
 import "./session-manager.js";
 import "./settingsStore.js";