refactor: initial decoupling of electron

Author: jonathanlab

.github/workflows/build.yml

@@ -33,6 +33,9 @@ jobs:
       - name: Build electron-trpc
         run: pnpm --filter @posthog/electron-trpc build
 
+      - name: Build platform
+        run: pnpm --filter @posthog/platform build
+
       - name: Build shared
         run: pnpm --filter @posthog/shared build
 

.github/workflows/code-release.yml

@@ -85,6 +85,9 @@ jobs:
       - name: Build electron-trpc package
         run: pnpm --filter @posthog/electron-trpc run build
 
+      - name: Build platform package
+        run: pnpm --filter @posthog/platform run build
+
       - name: Build shared package
         run: pnpm --filter @posthog/shared run build
 
@@ -182,6 +185,9 @@ jobs:
       - name: Build electron-trpc package
         run: pnpm --filter @posthog/electron-trpc run build
 
+      - name: Build platform package
+        run: pnpm --filter @posthog/platform run build
+
       - name: Build shared package
         run: pnpm --filter @posthog/shared run build
 

.github/workflows/test.yml

@@ -78,6 +78,7 @@ jobs:
       - name: Build packages
         run: |
           pnpm --filter @posthog/electron-trpc build &
+          pnpm --filter @posthog/platform build &
           pnpm --filter @posthog/shared build
           pnpm --filter @posthog/git build
           pnpm --filter agent build &

apps/code/package.json

@@ -134,6 +134,7 @@
     "@posthog/quill-components": "link:/Users/adamleithp/Dev/posthog/packages/quill/packages/components",
     "@posthog/quill-primitives": "link:/Users/adamleithp/Dev/posthog/packages/quill/packages/primitives",
     "@posthog/quill-tokens": "link:/Users/adamleithp/Dev/posthog/packages/quill/packages/tokens",
+    "@posthog/platform": "workspace:*",
     "@posthog/shared": "workspace:*",
     "@radix-ui/react-collapsible": "^1.1.12",
     "@radix-ui/react-icons": "^1.3.2",

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

@@ -9,6 +9,7 @@ import { SuspensionRepositoryImpl } from "../db/repositories/suspension-reposito
 import { WorkspaceRepository } from "../db/repositories/workspace-repository";
 import { WorktreeRepository } from "../db/repositories/worktree-repository";
 import { DatabaseService } from "../db/service";
+import { ElectronUrlLauncher } from "../platform-adapters/electron-url-launcher";
 import { AgentAuthAdapter } from "../services/agent/auth-adapter";
 import { AgentService } from "../services/agent/service";
 import { AppLifecycleService } from "../services/app-lifecycle/service";
@@ -52,6 +53,8 @@ export const container = new Container({
   defaultScope: "Singleton",
 });
 
+container.bind(MAIN_TOKENS.UrlLauncher).to(ElectronUrlLauncher);
+
 container.bind(MAIN_TOKENS.DatabaseService).to(DatabaseService);
 container
   .bind(MAIN_TOKENS.AuthPreferenceRepository)

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

@@ -5,6 +5,9 @@
  * Never import this file from renderer code.
  */
 export const MAIN_TOKENS = Object.freeze({
+  // Platform ports (host-agnostic interfaces from @posthog/platform)
+  UrlLauncher: Symbol.for("Platform.UrlLauncher"),
+
   // Stores
   SettingsStore: Symbol.for("Main.SettingsStore"),
 

apps/code/src/main/platform-adapters/electron-url-launcher.ts

@@ -0,0 +1,10 @@
+import type { IUrlLauncher } from "@posthog/platform/url-launcher";
+import { shell } from "electron";
+import { injectable } from "inversify";
+
+@injectable()
+export class ElectronUrlLauncher implements IUrlLauncher {
+  public async launch(url: string): Promise<void> {
+    await shell.openExternal(url);
+  }
+}

apps/code/src/main/services/github-integration/service.ts

@@ -1,13 +1,18 @@
+import type { IUrlLauncher } from "@posthog/platform/url-launcher";
 import { getCloudUrlFromRegion } from "@shared/constants/oauth";
-import { shell } from "electron";
-import { injectable } from "inversify";
+import { inject, injectable } from "inversify";
+import { MAIN_TOKENS } from "../../di/tokens";
 import { logger } from "../../utils/logger";
 import type { CloudRegion, StartGitHubFlowOutput } from "./schemas";
 
 const log = logger.scope("github-integration-service");
 
 @injectable()
 export class GitHubIntegrationService {
+  constructor(
+    @inject(MAIN_TOKENS.UrlLauncher) private readonly urlLauncher: IUrlLauncher,
+  ) {}
+
   public async startFlow(
     region: CloudRegion,
     projectId: number,
@@ -18,7 +23,7 @@ export class GitHubIntegrationService {
       const authorizeUrl = `${cloudUrl}/api/environments/${projectId}/integrations/authorize/?kind=github&next=${encodeURIComponent(next)}`;
 
       log.info("Opening GitHub authorization URL in browser");
-      await shell.openExternal(authorizeUrl);
+      await this.urlLauncher.launch(authorizeUrl);
 
       return { success: true };
     } catch (error) {

biome.jsonc

@@ -128,6 +128,31 @@
         }
       }
     },
+    {
+      // Main-process code must not import from "electron" directly.
+      // Electron APIs go through platform ports (@posthog/platform) implemented
+      // by adapters in apps/code/src/main/platform-adapters/. This keeps the
+      // service layer host-agnostic so it can later run as a standalone Node server.
+      //
+      // The ban is opt-in per migrated area. As each service is refactored to
+      // depend on platform ports, add its folder to this includes list. When the
+      // entire main process is migrated, simplify to "apps/code/src/main/**/*.ts".
+      "includes": ["apps/code/src/main/services/github-integration/**/*.ts"],
+      "linter": {
+        "rules": {
+          "style": {
+            "noRestrictedImports": {
+              "level": "error",
+              "options": {
+                "paths": {
+                  "electron": "Do not import from 'electron' in main-process services. Define a port interface in @posthog/platform and implement it as an adapter in apps/code/src/main/platform-adapters/. The service should depend on the port via DI."
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     {
       // Renderer code should use path aliases
       "includes": [

mprocs.yaml

@@ -6,13 +6,17 @@ procs:
     depends_on:
       - agent
       - git
+      - platform
 
   agent:
     shell: 'node scripts/pnpm-run.mjs --filter agent run dev'
 
   git:
     shell: 'node scripts/pnpm-run.mjs --filter @posthog/git run dev'
 
+  platform:
+    shell: 'node scripts/pnpm-run.mjs --filter @posthog/platform run dev'
+
   enricher:
     shell: 'node scripts/pnpm-run.mjs --filter @posthog/enricher run dev'