Refactor extension handling by removing explicit imports and implementing automatic side-effect imports via Vite plugin. Update documentation to reflect changes in extension management.

Author: erdalkaraca

packages/app-e2e/README.md

@@ -21,7 +21,7 @@ Minimal Docks shell for Playwright only (not the public demo app in `packages/ap
 Entry is [src/main.ts](./src/main.ts): `registerApp` plus auxiliary/toolbar contributions as specs require.
 
 - **Extensions:** list them in `AppDefinition.extensions` (e.g. `@eclipse-docks/extension-ai-system`, `@eclipse-docks/extension-monaco-editor` for workspace file editing in E2E).
-- **Static side-effect import:** [src/extensions.ts](./src/extensions.ts) loads the AI extension’s registration module **before** `main.ts` registers E2E auxiliary tabs so order is **`[aiview, …e2e tabs]`**. That avoids `wa-tab-group` “first tab” fallbacks being mistaken for successful `coupledEditors` coupling.
+- **Side-effect imports:** [vite.config.ts](./vite.config.ts) uses `resolveDepVersionsPlugin()` (automatic `@eclipse-docks/extension-*` side-effect imports are on by default). [src/main.ts](./src/main.ts) additionally imports the in-repo [`extension-ai-system/src/ai-system-extension.ts`](../../packages/extension-ai-system/src/ai-system-extension.ts) so that registration runs after the package entry and **before** the rest of `main.ts` adds E2E auxiliary tabs — order **`[aiview, …e2e tabs]`** — avoiding `wa-tab-group` “first tab” fallbacks being mistaken for successful `coupledEditors` coupling.
 
 ### `coupledEditors` example
 

packages/app-e2e/src/extensions.ts

@@ -1,3 +1,9 @@
+/**
+ * In-repo AI extension registration (after package entry from resolveDepVersionsPlugin’s default extension side-effects).
+ * Keeps auxiliary tab order before E2E contributions (see README).
+ */
+import '../../extension-ai-system/src/ai-system-extension';
+
 import {
     TOOLBAR_MAIN,
     SIDEBAR_AUXILIARY,
@@ -7,7 +13,6 @@ import {
 } from '@eclipse-docks/core';
 import { html } from '@eclipse-docks/core/externals/lit';
 
-import './extensions';
 import './e2e-coupled-panel';
 
 contributionRegistry.registerContribution(SIDEBAR_AUXILIARY, {

packages/app-e2e/src/main.ts

@@ -2,7 +2,6 @@ import { TOOLBAR_MAIN, appLoaderService, contributionRegistry, type HTMLContribu
 import { html } from '@eclipse-docks/core/externals/lit';
 import { fetchReleases } from "@eclipse-docks/extension-github-service";
 
-import './extensions';
 import './dashboard-layout';
 
 contributionRegistry.registerContribution(TOOLBAR_MAIN, {

packages/app/src/extensions.ts

@@ -93,20 +93,161 @@ export function resolveDepVersions(
 
 const RESOLVED_PACKAGE_INFO_KEY = '__RESOLVED_PACKAGE_INFO__';
 
-export function resolveDepVersionsPlugin(options?: {
+/** Virtual module id; injected into `index.html` before `main.ts` when extension side-effects are enabled. */
+export const VIRTUAL_EXTENSION_IMPORTS = 'virtual:eclipse-docks-extension-imports';
+
+const RESOLVED_VIRTUAL_EXTENSION_IMPORTS = `\0${VIRTUAL_EXTENSION_IMPORTS}`;
+
+const DEFAULT_EXTENSION_PATTERN = /^@eclipse-docks\/extension-/;
+
+const DEFAULT_PRIORITY_FIRST = ['@eclipse-docks/extension-pwa'];
+
+/** Matches Vite’s default app entry in index.html. */
+const MAIN_TS_SCRIPT_RE =
+  /<script\b[^>]*\btype\s*=\s*["']module["'][^>]*\bsrc\s*=\s*["'][^"']*\/src\/main\.ts["'][^>]*>\s*<\/script>/i;
+
+export interface ExtensionSideEffectsOptions {
+  /**
+   * When false, disables automatic extension side-effect imports. Omitted or true keeps them on.
+   */
+  enabled?: boolean;
+  /** Dependency names to skip (even if they match `packageNamePattern`). */
+  exclude?: string[];
+  /**
+   * Packages to load first, in order (only those present in dependencies are imported).
+   * Default includes PWA so `beforeinstallprompt` can register early.
+   */
+  priorityFirst?: string[];
+  /**
+   * Which direct `dependencies` keys qualify as Eclipse Docks extensions.
+   * @default /^@eclipse-docks\/extension-/
+   */
+  packageNamePattern?: RegExp;
+}
+
+export type ResolveDepVersionsPluginOptions = {
   includeDevDependencies?: boolean;
-}): Plugin {
+  /**
+   * By default, registers a virtual module that side-effect-imports every matching direct
+   * `dependencies` entry (see `ExtensionSideEffectsOptions`), and injects
+   * `import 'virtual:eclipse-docks-extension-imports'` into `index.html` **before** `/src/main.ts`.
+   * Pass `false` or `{ enabled: false }` to disable.
+   */
+  extensionSideEffects?: boolean | ExtensionSideEffectsOptions;
+};
+
+/** Normalized match options for {@link listExtensionSideEffectPackages}. */
+export type ExtensionSideEffectsListOptions = {
+  exclude: Set<string>;
+  priorityFirst: string[];
+  pattern: RegExp;
+};
+
+function normalizeExtensionSideEffects(
+  opt: boolean | ExtensionSideEffectsOptions | undefined,
+): ExtensionSideEffectsListOptions | null {
+  if (opt === false) return null;
+  if (opt === undefined || opt === true) {
+    return {
+      exclude: new Set(),
+      priorityFirst: [...DEFAULT_PRIORITY_FIRST],
+      pattern: DEFAULT_EXTENSION_PATTERN,
+    };
+  }
+  if (opt.enabled === false) return null;
+  return {
+    exclude: new Set(opt.exclude ?? []),
+    priorityFirst: opt.priorityFirst ?? [...DEFAULT_PRIORITY_FIRST],
+    pattern: opt.packageNamePattern ?? DEFAULT_EXTENSION_PATTERN,
+  };
+}
+
+export function listExtensionSideEffectPackages(
+  dependencies: Record<string, string>,
+  sideEffects: ExtensionSideEffectsListOptions,
+): string[] {
+  const names = Object.keys(dependencies).filter(
+    (name) => sideEffects.pattern.test(name) && !sideEffects.exclude.has(name),
+  );
+  const prioritySet = new Set(sideEffects.priorityFirst);
+  const first = sideEffects.priorityFirst.filter((p) => names.includes(p));
+  const rest = names.filter((n) => !prioritySet.has(n)).sort((a, b) => a.localeCompare(b));
+  return [...first, ...rest];
+}
+
+export function resolveDepVersionsPlugin(
+  options?: ResolveDepVersionsPluginOptions,
+): Plugin {
+  let appRoot = process.cwd();
+  let extensionSideEffectsActive = false;
+  let extensionImportPackages: string[] = [];
+
   return {
     name: 'resolve-dep-versions',
     config(config) {
       const root = config.root ? path.resolve(config.root) : process.cwd();
       const info = resolvePackageInfo(root, options);
-      const value = info ?? { name: '', version: '0.0.0', description: undefined, dependencies: {}, marketplaceCatalogUrls: undefined };
+      const value =
+        info ?? {
+          name: '',
+          version: '0.0.0',
+          description: undefined,
+          dependencies: {},
+          marketplaceCatalogUrls: undefined,
+        };
       return {
         define: {
           [RESOLVED_PACKAGE_INFO_KEY]: JSON.stringify(value),
         },
       };
     },
+    configResolved(config) {
+      appRoot = path.resolve(config.root ?? process.cwd());
+      const normalized = normalizeExtensionSideEffects(options?.extensionSideEffects);
+      extensionSideEffectsActive = normalized !== null;
+      if (!normalized) {
+        extensionImportPackages = [];
+        return;
+      }
+      const info = resolvePackageInfo(appRoot, options);
+      extensionImportPackages = listExtensionSideEffectPackages(
+        info?.dependencies ?? {},
+        normalized,
+      );
+    },
+    resolveId(id) {
+      if (id === VIRTUAL_EXTENSION_IMPORTS) {
+        return RESOLVED_VIRTUAL_EXTENSION_IMPORTS;
+      }
+      return undefined;
+    },
+    load(id) {
+      if (id !== RESOLVED_VIRTUAL_EXTENSION_IMPORTS) {
+        return null;
+      }
+      if (extensionImportPackages.length === 0) {
+        return 'export {};\n';
+      }
+      return extensionImportPackages.map((pkg) => `import ${JSON.stringify(pkg)};\n`).join('');
+    },
+    transformIndexHtml: {
+      order: 'pre',
+      handler(html) {
+        if (!extensionSideEffectsActive) {
+          return html;
+        }
+        if (extensionImportPackages.length === 0) {
+          return html;
+        }
+        if (html.includes(VIRTUAL_EXTENSION_IMPORTS)) {
+          return html;
+        }
+        if (!MAIN_TS_SCRIPT_RE.test(html)) {
+          return html;
+        }
+        const inject = `<script type="module">import ${JSON.stringify(VIRTUAL_EXTENSION_IMPORTS)};</script>\n`;
+        return html.replace(MAIN_TS_SCRIPT_RE, (match) => `${inject}${match}`);
+      },
+    },
   };
 }