Architecture: How to eliminate hardcoded dev ports in the Chrome extension...

Documentation for Sessions

🏗️ Architecture: How to eliminate hardcoded dev ports in the Chrome extension...

Date: 2026-02-11
Time: 12:26:51 UTC
Session: gspace1-105.6
Agent: backend
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How to eliminate hardcoded dev ports in the Chrome extension?

Task: Eliminate hardcoded localhost ports in Chrome extension

🎯 Decision Made

Chosen:

Two-layer approach: (1) Content scripts derive AI port from window.location.port using Math.floor(port/1000)*1000+400 convention. (2) Extension pages (popup, sidepanel, options, service worker) load a generated dev-ports.js from .env.local via script tags/importScripts, with editor2 fallback defaults in env-config.js.

Options Considered:

Auto-detect from window.location.port only
Generate file from .env.local only
Two-layer: page port derivation for content scripts + generated file for extension pages
Store ports in chrome.storage.local

💭 Reasoning

Content scripts run on the web page and can detect the workspace port directly — no external file needed. Extension context pages can't detect page ports, so they use a generated file from .env.local. The convention (editor2=5xxx, gspace1=6xxx, AI always at x400) is simple and reliable. The generated file is gitignored since it's workspace-specific, and all consumers have fallback defaults so missing file doesn't break anything. Chrome manifest content_scripts errors if a listed file doesn't exist, so dev-ports.js is NOT listed there — content scripts use port derivation instead.

📁 Files Involved

apps/gograb-ai-extension/scripts/generate-dev-ports.js
apps/gograb-ai-extension/shared/env-config.js
apps/gograb-ai-extension/shared/dev-ports.js
apps/gograb-ai-extension/content/inject.js
apps/gograb-ai-extension/manifest.json
apps/gograb-ai-extension/background/service-worker.js
apps/gograb-ai-extension/background/mcp-connector.js
apps/gograb-ai-extension/options/options.js

🔗 Related

Decision ID: dev_1770812811081_hb8ie2r
Session: 105
Workspace: gspace1

Auto-generated by MCP Smart Consolidation