feat: DH-21221: Remote python controller imports

__mocks__/vscode.ts

@@ -129,18 +129,28 @@ export class DiagnosticCollection
 }
 
 export class EventEmitter<T> {
-  listeners = new Set<(...args: any[]) => void>();
-  event = (listener: (e: T) => any) => {
-    this.listeners.add(listener);
-    return () => {
-      this.listeners.delete(listener);
-    };
-  };
+  private listeners = new Set<(data: T) => any>();
+
+  event = vi
+    .fn()
+    .mockName('event')
+    .mockImplementation((listener: (e: T) => any) => {
+      this.listeners.add(listener);
+      return {
+        dispose: vi
+          .fn()
+          .mockName('dispose')
+          .mockImplementation(() => {
+            this.listeners.delete(listener);
+          }),
+      };
+    });
+
   fire = vi
     .fn()
     .mockName('fire')
-    .mockImplementation((event: T) => {
-      this.listeners.forEach(listener => listener(event));
+    .mockImplementation((data: T): void => {
+      this.listeners.forEach(listener => listener(data));
     });
 }
 
@@ -354,7 +364,10 @@ export class Uri {
   static joinPath = vi
     .fn()
     .mockName('joinPath')
-    .mockImplementation((...args) => Uri.parse(args.join('/')));
+    .mockImplementation((...args) => {
+      const filteredArgs = args.filter(a => a.toString().length > 0);
+      return Uri.parse(filteredArgs.join('/'));
+    });
 
   static parse = vi
     .fn()

docs/python-remote-file-sourcing.md

@@ -156,3 +156,74 @@ def dashboard_content(table):
 2. In your VS Code workspace, use the Deephaven extension to run `main.py`. The imports will resolve because the `stock_ticker` folder is registered as a remote file source.
 
 ![Run main.py](assets/run-main-py.gif)
+
+## Controller Import Prefix Support (Enterprise)
+
+**Deephaven Enterprise** uses a controller import registration mechanism (`meta_import()`) that requires modules to be importable under a prefixed name (e.g., `controller.mymodule`) for the server to find them. The VS Code extension automatically detects this pattern in your Python code and registers both the unprefixed and prefixed names with the server for each folder marked as a remote file source, allowing prefixed imports to be sourced by the extension.
+
+### Auto-Detection
+
+When you run Python code, the extension scans for `meta_import()` calls and infers the prefix to use. No extra setup is required — if your code already calls `meta_import()`, the extension picks it up automatically.
+
+**With default prefix (`controller`):**
+
+```python
+import deephaven_enterprise.controller_import
+
+deephaven_enterprise.controller_import.meta_import()
+```
+
+**With a custom prefix:**
+
+```python
+import deephaven_enterprise.controller_import
+
+deephaven_enterprise.controller_import.meta_import("myprefix")
+```
+
+**From-import style:**
+
+```python
+from deephaven_enterprise.controller_import import meta_import
+
+meta_import("custom")
+```
+
+### Behavior
+
+- For each folder marked as a remote file source, both the unprefixed and prefixed module names are registered with the Deephaven server.
+- Example: If you mark a folder called `mymodule` and a prefix of `controller` is detected, the server will receive both `mymodule` and `controller.mymodule` as importable names for that folder.
+- Without a detected or configured prefix, only the unprefixed name (`mymodule`) is registered for each marked folder.
+- Prefixes are **updated when you run Python code**: running a full file replaces any previous prefixes; running a snippet updates prefixes only if a `meta_import()` call is found in that snippet.
+
+### Manual Override
+
+You can set one or more prefixes explicitly in your VS Code settings:
+
+```json
+"deephaven.importPrefixes": ["controller"]
+```
+
+When set, this array is used as the source of truth and auto-detection is skipped entirely. Multiple prefixes can be provided if needed:
+
+```json
+"deephaven.importPrefixes": ["controller", "custom"]
+```
+
+The main reasons to set this manually are:
+
+- **Unrecognized imports** — the auto-detection doesn't recognize all possible import patterns such as aliasing:
+
+  ```python
+  import deephaven_enterprise.controller_import as ci
+
+  ci.meta_import()
+
+  from deephaven_enterprise.controller_import import meta_import as m
+
+  m()
+  ```
+
+- **`meta_import()` in a dependency** — auto-detection only scans the code being run directly, not modules it imports. If the registration happens inside a dependency rather than the script itself, the prefix will not be detected.
+
+If either case applies, set `deephaven.importPrefixes` manually.

package.json

@@ -160,6 +160,17 @@
           },
           "default": []
         },
+        "deephaven.importPrefixes": {
+          "type": [
+            "array",
+            "null"
+          ],
+          "default": null,
+          "items": {
+            "type": "string"
+          },
+          "markdownDescription": "Optional controller import prefixes for remote file sourcing. When set, overrides automatic detection from `meta_import()` calls in Python code. Defaults to automatic detection if not specified."
+        },
         "deephaven.mcp.enabled": {
           "type": "boolean",
           "default": false,

src/common/constants.ts

@@ -16,6 +16,7 @@ export const CONFIG_KEY = {
   root: 'deephaven',
   coreServers: 'coreServers',
   enterpriseServers: 'enterpriseServers',
+  importPrefixes: 'importPrefixes',
   mcpAutoUpdateConfig: 'mcp.autoUpdateConfig',
   mcpDocsEnabled: 'mcp.docsEnabled',
   mcpEnabled: 'mcp.enabled',

src/services/ConfigService.spec.ts

@@ -353,3 +353,39 @@ describe('updateWindsurfMcpConfig', () => {
     expect(getEnsuredContent).toHaveBeenCalledWith(windowsConfigUri, '{}\n');
   });
 });
+
+describe('getImportPrefixes', () => {
+  it.each([
+    ['not configured', undefined, undefined],
+    ['empty array', [], []],
+    ['single valid prefix', ['controller'], ['controller']],
+    ['multiple valid prefixes', ['controller', '_my_prefix'], ['controller', '_my_prefix']],
+  ])('should return without errors when %s', (_label, given, expected) => {
+    configMap.set(CONFIG_KEY.importPrefixes, given);
+
+    const result = ConfigService.getImportPrefixes();
+
+    expect(result).toEqual(expected);
+    expect(vscode.window.showErrorMessage).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['one invalid entry (empty string)', [''], [], ['']],
+    ['one invalid entry (starts with digit)', ['1controller'], [], ['1controller']],
+    ['one invalid entry (contains hyphen)', ['my-prefix'], [], ['my-prefix']],
+    ['one invalid entry (dotted name)', ['my.prefix'], [], ['my.prefix']],
+    ['mixed valid and invalid entries', ['valid', '1bad', 'also_valid', 'my-prefix'], ['valid', 'also_valid'], ['1bad', 'my-prefix']],
+  ])('should filter invalid entries and show errors when %s', (_label, given, expectedResult, expectedInvalid) => {
+    configMap.set(CONFIG_KEY.importPrefixes, given);
+
+    const result = ConfigService.getImportPrefixes();
+
+    expect(result).toEqual(expectedResult);
+    expect(vscode.window.showErrorMessage).toHaveBeenCalledTimes(expectedInvalid.length);
+    for (const invalid of expectedInvalid) {
+      expect(vscode.window.showErrorMessage).toHaveBeenCalledWith(
+        expect.stringContaining(`'${invalid}' is not a valid import prefix name`)
+      );
+    }
+  });
+});

src/services/ConfigService.ts

@@ -78,6 +78,28 @@ function hasValidURL({ url }: { url: string }): boolean {
   }
 }
 
+// ASCII subset of Python identifier rules (PEP 3131 / py3 lexical spec allows Unicode,
+// but controller prefix names are expected to be ASCII in practice). A prefix is a
+// single identifier, not a dotted module path.
+const VALID_PYTHON_IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function getImportPrefixes(): string[] | undefined {
+  const config = getConfig().get<string[] | null>(CONFIG_KEY.importPrefixes);
+  if (config == null) {
+    return undefined;
+  }
+
+  return config.filter(prefix => {
+    if (VALID_PYTHON_IDENTIFIER_RE.test(prefix)) {
+      return true;
+    }
+    vscode.window.showErrorMessage(
+      `Invalid 'deephaven.importPrefixes' setting: '${prefix}' is not a valid import prefix name. It will be ignored.`
+    );
+    return false;
+  });
+}
+
 async function toggleMcp(enable?: boolean): Promise<void> {
   const currentState = isMcpEnabled();
   const targetState = enable ?? !currentState;
@@ -233,6 +255,7 @@ export async function updateWindsurfMcpConfig(
 export const ConfigService: IConfigService = {
   getCoreServers,
   getEnterpriseServers,
+  getImportPrefixes,
   isElectronFetchEnabled,
   isMcpDocsEnabled,
   isMcpEnabled,

src/services/DhcService.spec.ts

@@ -0,0 +1,152 @@
+import * as vscode from 'vscode';
+import type { dh as DhcType } from '@deephaven/jsapi-types';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { DhcService } from './DhcService';
+import { ConfigService } from './ConfigService';
+import type { RemoteFileSourceService } from './RemoteFileSourceService';
+import type { UniqueID } from '../types';
+
+vi.mock('vscode');
+
+vi.mock('./ConfigService', () => {
+  const mockConfigService = {
+    getImportPrefixes: vi.fn(),
+  };
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  return { ConfigService: mockConfigService };
+});
+
+/** Build a minimal DhcService instance that has a session already set up. */
+function createTestDhcService({
+  pythonRemoteFileSourcePlugin,
+  setControllerImportPrefixes = vi.fn(),
+  setPythonServerExecutionContext = vi.fn().mockResolvedValue(undefined),
+  sessionRunCode = vi.fn().mockResolvedValue({
+    error: '',
+    changes: { created: [], updated: [], removed: [] },
+  }),
+}: {
+  pythonRemoteFileSourcePlugin?: DhcType.Widget | null;
+  setControllerImportPrefixes?: ReturnType<typeof vi.fn>;
+  setPythonServerExecutionContext?: ReturnType<typeof vi.fn>;
+  sessionRunCode?: ReturnType<typeof vi.fn>;
+} = {}): DhcService {
+  const mockSession = {
+    runCode: sessionRunCode,
+  } as unknown as DhcType.IdeSession;
+
+  const mockCn = {
+    getConsoleTypes: vi.fn().mockResolvedValue(['python']),
+  } as unknown as DhcType.IdeConnection;
+
+  const mockRemoteFileSourceService = {
+    setControllerImportPrefixes,
+    setPythonServerExecutionContext,
+  } as unknown as RemoteFileSourceService;
+
+  const mockDiagnosticsCollection = {
+    set: vi.fn(),
+    clear: vi.fn(),
+  } as unknown as vscode.DiagnosticCollection;
+
+  const service = Object.assign(Object.create(DhcService.prototype), {
+    session: mockSession,
+    cn: mockCn,
+    cnId: 'test-cn-id' as UniqueID,
+    pythonRemoteFileSourcePlugin:
+      pythonRemoteFileSourcePlugin !== undefined
+        ? pythonRemoteFileSourcePlugin
+        : ({} as DhcType.Widget),
+    groovyRemoteFileSourcePluginService: null,
+    remoteFileSourceService: mockRemoteFileSourceService,
+    diagnosticsCollection: mockDiagnosticsCollection,
+    groovyDiagnosticsCollection: mockDiagnosticsCollection,
+    outputChannel: {
+      appendLine: vi.fn(),
+      show: vi.fn(),
+    } as unknown as vscode.OutputChannel,
+    toaster: { error: vi.fn(), info: vi.fn() },
+    _isRunningCode: false,
+    _onDidChangeRunningCodeStatus: { fire: vi.fn() },
+    disposables: { add: vi.fn() },
+    serverUrl: new URL('http://localhost:10000/'),
+  });
+
+  return service;
+}
+
+function mockTextDoc(codeText: string): vscode.TextDocument {
+  return {
+    uri: vscode.Uri.file('/path/to/file.py'),
+    getText: vi.fn().mockReturnValue(codeText),
+  } as unknown as vscode.TextDocument;
+}
+
+describe('DhcService.runCode – importPrefixes setting', () => {
+  const mockSetControllerImportPrefixes = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it.each([
+    {
+      label: 'uses setting prefixes when configured',
+      configPrefixes: ['myPrefix'],
+      input: 'x = 1',
+      expected: new Set(['myPrefix']),
+    },
+    {
+      label: 'uses all prefixes when multiple configured',
+      configPrefixes: ['prefix1', 'prefix2'],
+      input: 'x = 1',
+      expected: new Set(['prefix1', 'prefix2']),
+    },
+    {
+      label: 'falls back to extraction when undefined and code has prefixes',
+      configPrefixes: undefined,
+      input: 'deephaven_enterprise.controller_import.meta_import("myPrefix")\n',
+      expected: new Set(['myPrefix']),
+    },
+    {
+      label: 'skips call when undefined and no prefixes in snippet',
+      configPrefixes: undefined,
+      input: 'x = 1',
+      expected: null,
+    },
+    {
+      label: 'calls with empty set for full file runs even when no prefixes found',
+      configPrefixes: undefined,
+      input: mockTextDoc('x = 1'),
+      expected: new Set(),
+    },
+    {
+      label: 'setting takes precedence over meta_import in code',
+      configPrefixes: ['forced'],
+      input: 'deephaven_enterprise.controller_import.meta_import("otherPrefix")\n',
+      expected: new Set(['forced']),
+    },
+    {
+      label: 'setting takes precedence over meta_import in text doc',
+      configPrefixes: ['forced'],
+      input: mockTextDoc(
+        'deephaven_enterprise.controller_import.meta_import("otherPrefix")\n'
+      ),
+      expected: new Set(['forced']),
+    },
+  ])('$label', async ({ configPrefixes, input, expected }) => {
+    vi.mocked(ConfigService.getImportPrefixes).mockReturnValue(configPrefixes);
+
+    const service = createTestDhcService({
+      setControllerImportPrefixes: mockSetControllerImportPrefixes,
+    });
+
+    await service.runCode(input, 'python');
+
+    if (expected == null) {
+      expect(mockSetControllerImportPrefixes).not.toHaveBeenCalled();
+    } else {
+      expect(mockSetControllerImportPrefixes).toHaveBeenCalledWith(expected);
+    }
+  });
+});