Init task deep linking

Author: charlesvien

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

@@ -12,6 +12,7 @@ import { OAuthService } from "../services/oauth/service.js";
 import { ShellService } from "../services/shell/service.js";
 import { UpdatesService } from "../services/updates/service.js";
 import { MAIN_TOKENS } from "./tokens.js";
+import { TaskLinkService } from "../services/task-link/service.js";
 
 export const container = new Container({
   defaultScope: "Singleton",
@@ -28,3 +29,7 @@ container.bind(MAIN_TOKENS.GitService).to(GitService);
 container.bind(MAIN_TOKENS.OAuthService).to(OAuthService);
 container.bind(MAIN_TOKENS.ShellService).to(ShellService);
 container.bind(MAIN_TOKENS.UpdatesService).to(UpdatesService);
+container.bind(MAIN_TOKENS.GitService).to(GitService);
+container.bind(MAIN_TOKENS.DeepLinkService).to(DeepLinkService);
+container.bind(MAIN_TOKENS.OAuthService).to(OAuthService);
+container.bind(MAIN_TOKENS.TaskLinkService).to(TaskLinkService);

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

@@ -17,4 +17,5 @@ export const MAIN_TOKENS = Object.freeze({
   OAuthService: Symbol.for("Main.OAuthService"),
   ShellService: Symbol.for("Main.ShellService"),
   UpdatesService: Symbol.for("Main.UpdatesService"),
+  TaskLinkService: Symbol.for("Main.TaskLinkService"),
 });

apps/array/src/main/index.ts

@@ -45,6 +45,8 @@ import {
 } from "./services/posthog-analytics.js";
 import type { UpdatesService } from "./services/updates/service.js";
 import { registerWorkspaceIpc } from "./services/workspace/index.js";
+import { registerWorktreeIpc } from "./services/worktree.js";
+import { TaskLinkService } from "./services/task-link/service";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -322,6 +324,11 @@ app.whenReady().then(() => {
   // Initialize services that need early startup
   container.get<DockBadgeService>(MAIN_TOKENS.DockBadgeService);
   container.get<UpdatesService>(MAIN_TOKENS.UpdatesService);
+  const taskLinkService = container.get<TaskLinkService>(MAIN_TOKENS.TaskLinkService);
+  deepLinkService.registerHandler(
+    "task",
+    taskLinkService.getDeepLinkHandler(),
+  );
 
   // Initialize PostHog analytics
   initializePostHog();

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

@@ -6,17 +6,16 @@ const log = logger.scope("deep-link-service");
 
 const PROTOCOL = "array";
 
-export type DeepLinkHandler = (url: URL) => boolean;
+export type DeepLinkHandler = (
+  path: string,
+  searchParams: URLSearchParams,
+) => 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;
@@ -39,30 +38,22 @@ export class DeepLinkService {
     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}`);
+  public registerHandler(key: string, handler: DeepLinkHandler): void {
+    if (this.handlers.has(key)) {
+      log.warn(`Overwriting existing handler for key: ${key}`);
     }
-    this.handlers.set(path, handler);
-    log.info(`Registered deep link handler for path: ${path}`);
+    this.handlers.set(key, handler);
+    log.info(`Registered deep link handler for key: ${key}`);
   }
 
-  /**
-   * Unregister a handler for a specific path.
-   */
-  public unregisterHandler(path: string): void {
-    this.handlers.delete(path);
+  public unregisterHandler(key: string): void {
+    this.handlers.delete(key);
   }
 
   /**
-   * 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
+   * Handle an incoming deep link URL
+   * 
+   * NOTE: Strips the protocol and main key, passing only dynamic segments to handlers.
    */
   public handleUrl(url: string): boolean {
     log.info("Received deep link:", url);
@@ -75,36 +66,31 @@ export class DeepLinkService {
     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);
+      // The hostname is the main key (e.g., "task" in array://task/...)
+      const mainKey = parsedUrl.hostname;
 
-      const handler = this.handlers.get(path);
-      if (handler) {
-        return handler(parsedUrl);
+      if (!mainKey) {
+        log.warn("Deep link has no main key:", url);
+        return false;
       }
 
-      // 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);
-        }
+      const handler = this.handlers.get(mainKey);
+      if (!handler) {
+        log.warn("No handler registered for deep link key:", mainKey);
+        return false;
       }
 
-      log.warn("No handler registered for deep link path:", path);
-      return false;
+      // Extract path segments after the main key (strip leading slash)
+      const pathSegments = parsedUrl.pathname.slice(1);
+
+      log.info(`Routing deep link to '${mainKey}' handler with path: ${pathSegments || "(empty)"}`);
+      return handler(pathSegments, parsedUrl.searchParams);
     } 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/oauth/service.ts

@@ -52,15 +52,15 @@ export class OAuthService {
     private readonly deepLinkService: DeepLinkService,
   ) {
     // Register OAuth callback handler for deep links
-    this.deepLinkService.registerHandler("callback", (url) =>
-      this.handleOAuthCallback(url),
+    this.deepLinkService.registerHandler("callback", (_path, searchParams) =>
+      this.handleOAuthCallback(searchParams),
     );
     log.info("Registered OAuth callback handler for deep links");
   }
 
-  private handleOAuthCallback(url: URL): boolean {
-    const code = url.searchParams.get("code");
-    const error = url.searchParams.get("error");
+  private handleOAuthCallback(searchParams: URLSearchParams): boolean {
+    const code = searchParams.get("code");
+    const error = searchParams.get("error");
 
     if (!this.pendingFlow) {
       log.warn("Received OAuth callback but no pending flow");

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

@@ -0,0 +1,53 @@
+import { EventEmitter } from "node:events";
+import { injectable } from "inversify";
+import { logger } from "../../lib/logger.js";
+import { getMainWindow } from "../../trpc/context.js";
+import type { DeepLinkHandler } from "../deep-link/service.js";
+
+const log = logger.scope("task-link-service");
+
+@injectable()
+export class TaskLinkService {
+  private emitter = new EventEmitter();
+
+  /**
+   * Get the deep link handler for task links.
+   * Register this with DeepLinkService for the "task" key.
+   * Expects URLs like: array://task/{taskId}
+   */
+  public getDeepLinkHandler(): DeepLinkHandler {
+    return (path) => this.handleTaskLink(path);
+  }
+
+  /**
+   * Subscribe to task link events.
+   */
+  public onTaskLink(callback: (taskId: string) => void): () => void {
+    this.emitter.on("task", callback);
+    return () => this.emitter.off("task", callback);
+  }
+
+  private handleTaskLink(path: string): boolean {
+    // path is just the taskId (e.g., "abc123" from array://task/abc123)
+    const taskId = path.split("/")[0];
+
+    if (!taskId) {
+      log.warn("Task link missing task ID");
+      return false;
+    }
+
+    log.info(`Emitting task link event: ${taskId}`);
+    this.emitter.emit("task", taskId);
+
+    // Focus the window
+    const mainWindow = getMainWindow();
+    if (mainWindow) {
+      if (mainWindow.isMinimized()) {
+        mainWindow.restore();
+      }
+      mainWindow.focus();
+    }
+
+    return true;
+  }
+}

apps/array/src/main/trpc/router.ts

@@ -1,5 +1,6 @@
 import { contextMenuRouter } from "./routers/context-menu.js";
 import { dockBadgeRouter } from "./routers/dock-badge.js";
+import { deepLinkRouter } from "./routers/deep-link.js";
 import { encryptionRouter } from "./routers/encryption.js";
 import { externalAppsRouter } from "./routers/external-apps.js";
 import { fileWatcherRouter } from "./routers/file-watcher.js";
@@ -29,6 +30,7 @@ export const trpcRouter = router({
   secureStore: secureStoreRouter,
   shell: shellRouter,
   updates: updatesRouter,
+  deepLink: deepLinkRouter,
 });
 
 export type TrpcRouter = typeof trpcRouter;

apps/array/src/main/trpc/routers/deep-link.ts

@@ -0,0 +1,39 @@
+import { get } from "../../di/container.js";
+import { MAIN_TOKENS } from "../../di/tokens.js";
+import type { TaskLinkService } from "../../services/task-link/service.js";
+import { publicProcedure, router } from "../trpc.js";
+
+export const deepLinkRouter = router({
+  /**
+   * Subscribe to task link deep link events.
+   * Emits task ID when array://task/{taskId} is opened.
+   */
+  onOpenTask: publicProcedure.subscription(async function* () {
+    const taskLinkService = get<TaskLinkService>(MAIN_TOKENS.TaskLinkService);
+
+    // Create a queue to buffer events
+    const queue: string[] = [];
+    let resolve: (() => void) | null = null;
+
+    const unsubscribe = taskLinkService.onTaskLink((taskId) => {
+      queue.push(taskId);
+      resolve?.();
+    });
+
+    try {
+      while (true) {
+        if (queue.length === 0) {
+          await new Promise<void>((r) => {
+            resolve = r;
+          });
+        }
+        const taskId = queue.shift();
+        if (taskId) {
+          yield taskId;
+        }
+      }
+    } finally {
+      unsubscribe();
+    }
+  }),
+});