refactor: initial decoupling of electron

.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/scripts/postinstall.sh

@@ -8,6 +8,19 @@ set -e
 REPO_ROOT="$(cd ../.. && pwd)"
 SCRIPTS_DIR="$(cd "$(dirname "$0")" && pwd)"
 
+# Self-heal missing Electron binary.
+# pnpm skips package-level postinstall scripts when the lockfile is already
+# satisfied, so if node_modules/electron/dist gets wiped (interrupted download,
+# cache eviction, arch change, manual cleanup), `pnpm install` won't notice —
+# and `electron-forge start` then fails with "Electron failed to install
+# correctly, please delete node_modules/electron and try installing again".
+# Detect the missing binary and invoke Electron's own install script to fetch it.
+ELECTRON_DIST="$REPO_ROOT/node_modules/electron/dist"
+if [ ! -d "$ELECTRON_DIST" ] || [ -z "$(ls -A "$ELECTRON_DIST" 2>/dev/null)" ]; then
+  echo "Electron binary missing at $ELECTRON_DIST — downloading..."
+  node "$REPO_ROOT/node_modules/electron/install.js"
+fi
+
 echo "Rebuilding native modules for Electron..."
 
 cd "$REPO_ROOT"

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) {

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'
 

packages/platform/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@posthog/platform",
+  "version": "1.0.0",
+  "description": "Host-agnostic platform port interfaces. Zero runtime deps; implemented by per-host adapters (Electron, Node server, React Native, web).",
+  "type": "module",
+  "exports": {
+    "./url-launcher": {
+      "types": "./dist/url-launcher.d.ts",
+      "import": "./dist/url-launcher.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "node ../../scripts/rimraf.mjs dist .turbo"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.5.0"
+  },
+  "files": [
+    "dist/**/*",
+    "src/**/*"
+  ]
+}

packages/platform/src/url-launcher.ts

@@ -0,0 +1,3 @@
+export interface IUrlLauncher {
+  launch(url: string): Promise<void>;
+}

packages/platform/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

packages/platform/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/url-launcher.ts"],
+  format: ["esm"],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  splitting: false,
+  outDir: "dist",
+  target: "es2022",
+});