feat: Initial task deep linking (#283)

The "create if not exists locally" functionality needs work, unsure how to infer repoPath if it's never been setup. For now, it will open a task if you deep link to it, or if the app is opened for the first time by deep link if the task/workspace already existing locally.

Author: charlesvien

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

@@ -10,6 +10,7 @@ import { FsService } from "../services/fs/service.js";
 import { GitService } from "../services/git/service.js";
 import { OAuthService } from "../services/oauth/service.js";
 import { ShellService } from "../services/shell/service.js";
+import { TaskLinkService } from "../services/task-link/service.js";
 import { UpdatesService } from "../services/updates/service.js";
 import { MAIN_TOKENS } from "./tokens.js";
 
@@ -28,3 +29,4 @@ 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.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

@@ -43,6 +43,7 @@ import {
   shutdownPostHog,
   trackAppEvent,
 } from "./services/posthog-analytics.js";
+import type { TaskLinkService } from "./services/task-link/service";
 import type { UpdatesService } from "./services/updates/service.js";
 import { registerWorkspaceIpc } from "./services/workspace/index.js";
 
@@ -322,6 +323,7 @@ app.whenReady().then(() => {
   // Initialize services that need early startup
   container.get<DockBadgeService>(MAIN_TOKENS.DockBadgeService);
   container.get<UpdatesService>(MAIN_TOKENS.UpdatesService);
+  container.get<TaskLinkService>(MAIN_TOKENS.TaskLinkService);
 
   // 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,33 @@ 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,83 @@
+import { inject, injectable } from "inversify";
+import { MAIN_TOKENS } from "../../di/tokens.js";
+import { logger } from "../../lib/logger.js";
+import { TypedEventEmitter } from "../../lib/typed-event-emitter.js";
+import { getMainWindow } from "../../trpc/context.js";
+import type { DeepLinkService } from "../deep-link/service.js";
+
+const log = logger.scope("task-link-service");
+
+export const TaskLinkEvent = {
+  OpenTask: "openTask",
+} as const;
+
+export interface TaskLinkEvents {
+  [TaskLinkEvent.OpenTask]: { taskId: string };
+}
+
+@injectable()
+export class TaskLinkService extends TypedEventEmitter<TaskLinkEvents> {
+  /**
+   * Pending task ID that was received before renderer was ready.
+   * This handles the case where the app is launched via deep link.
+   */
+  private pendingTaskId: string | null = null;
+
+  constructor(
+    @inject(MAIN_TOKENS.DeepLinkService)
+    private readonly deepLinkService: DeepLinkService,
+  ) {
+    super();
+
+    this.deepLinkService.registerHandler("task", (path) =>
+      this.handleTaskLink(path),
+    );
+    log.info("Registered task link handler for deep links");
+  }
+
+  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;
+    }
+
+    // Check if renderer is ready (has any listeners)
+    const hasListeners = this.listenerCount(TaskLinkEvent.OpenTask) > 0;
+
+    if (hasListeners) {
+      log.info(`Emitting task link event: ${taskId}`);
+      this.emit(TaskLinkEvent.OpenTask, { taskId });
+    } else {
+      // Renderer not ready yet - queue it for later
+      log.info(`Queueing task link (renderer not ready): ${taskId}`);
+      this.pendingTaskId = taskId;
+    }
+
+    // Focus the window
+    const mainWindow = getMainWindow();
+    if (mainWindow) {
+      if (mainWindow.isMinimized()) {
+        mainWindow.restore();
+      }
+      mainWindow.focus();
+    }
+
+    return true;
+  }
+
+  /**
+   * Get and clear any pending task ID.
+   * Called by renderer on mount to handle deep links that arrived before it was ready.
+   */
+  public consumePendingTaskId(): string | null {
+    const taskId = this.pendingTaskId;
+    this.pendingTaskId = null;
+    if (taskId) {
+      log.info(`Consumed pending task link: ${taskId}`);
+    }
+    return taskId;
+  }
+}

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

@@ -1,4 +1,5 @@
 import { contextMenuRouter } from "./routers/context-menu.js";
+import { deepLinkRouter } from "./routers/deep-link.js";
 import { dockBadgeRouter } from "./routers/dock-badge.js";
 import { encryptionRouter } from "./routers/encryption.js";
 import { externalAppsRouter } from "./routers/external-apps.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 { on } from "node:events";
+import { container } from "../../di/container.js";
+import { MAIN_TOKENS } from "../../di/tokens.js";
+import {
+  TaskLinkEvent,
+  type TaskLinkEvents,
+  type TaskLinkService,
+} from "../../services/task-link/service.js";
+import { publicProcedure, router } from "../trpc.js";
+
+const getService = () =>
+  container.get<TaskLinkService>(MAIN_TOKENS.TaskLinkService);
+
+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* (opts) {
+    const service = getService();
+    const options = opts.signal ? { signal: opts.signal } : undefined;
+    for await (const [payload] of on(
+      service,
+      TaskLinkEvent.OpenTask,
+      options,
+    )) {
+      yield payload as TaskLinkEvents[typeof TaskLinkEvent.OpenTask];
+    }
+  }),
+
+  /**
+   * Get any pending task ID that arrived before renderer was ready.
+   * This handles the case where the app is launched via deep link.
+   */
+  getPendingTaskId: publicProcedure.query(() => {
+    const service = getService();
+    return service.consumePendingTaskId();
+  }),
+});

apps/array/src/renderer/components/MainLayout.tsx

@@ -20,16 +20,21 @@ import { useNavigationStore } from "@stores/navigationStore";
 import { useCallback, useEffect, useState } from "react";
 import { useHotkeys } from "react-hotkeys-hook";
 import { Toaster } from "sonner";
+import { useTaskDeepLink } from "../hooks/useTaskDeepLink";
 
 export function MainLayout() {
   const { view, toggleSettings, navigateToTaskInput, goBack, goForward } =
     useNavigationStore();
   const clearAllLayouts = usePanelLayoutStore((state) => state.clearAllLayouts);
   const toggleLeftSidebar = useSidebarStore((state) => state.toggle);
   const toggleRightSidebar = useRightSidebarStore((state) => state.toggle);
-  useIntegrations();
+
   const [commandMenuOpen, setCommandMenuOpen] = useState(false);
 
+  // Initialize integrations
+  useIntegrations();
+  useTaskDeepLink();
+
   const handleOpenSettings = useCallback(() => {
     toggleSettings();
   }, [toggleSettings]);