@theia/plugin-ext 1.76.0-next.6 → 1.76.0

package/src/hosted/browser-only/browser-only-plugin-file-system-provider.ts

@@ -0,0 +1,129 @@
+// *****************************************************************************
+// Copyright (C) 2026 Robert Jandow
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { inject, injectable } from '@theia/core/shared/inversify';
+import { Disposable, Event, Emitter, URI } from '@theia/core';
+import { Endpoint } from '@theia/core/lib/browser';
+import {
+    createFileSystemProviderError, FileChange, FileDeleteOptions, FileOverwriteOptions, FilePermission, FileSystemProvider, FileSystemProviderCapabilities,
+    FileSystemProviderErrorCode, FileType, FileWriteOptions, Stat, WatchOptions
+} from '@theia/filesystem/lib/common/files';
+import { FileService, FileServiceContribution } from '@theia/filesystem/lib/browser/file-service';
+import { PLUGINS_BASE_PATH, PLUGINS_SCHEME } from '@theia/plugin-utils/lib/common/constants';
+import { encodePluginAssetPath } from '@theia/plugin-utils/lib/common/plugin-model';
+
+/**
+ * Reads the plugin assets the build dropped under `PLUGINS_BASE_PATH`. With a backend those come
+ * off its disk via `file:`; browser-only has to fetch them over HTTP.
+ *
+ * Read-only, and only for what goes through the `FileService`: color themes, icon themes, icon
+ * fonts.
+ */
+@injectable()
+export class BrowserOnlyPluginFileSystemProvider implements FileSystemProvider {
+
+    readonly capabilities = FileSystemProviderCapabilities.Readonly | FileSystemProviderCapabilities.FileReadWrite | FileSystemProviderCapabilities.PathCaseSensitive;
+    readonly onDidChangeCapabilities = Event.None;
+    readonly onFileWatchError = Event.None;
+
+    protected readonly onDidChangeFileEmitter = new Emitter<readonly FileChange[]>();
+    readonly onDidChangeFile = this.onDidChangeFileEmitter.event;
+
+    watch(resource: URI, opts: WatchOptions): Disposable {
+        // baked into the build, nothing to watch
+        return Disposable.NULL;
+    }
+
+    async stat(resource: URI): Promise<Stat> {
+        const response = await this.fetch(resource, 'HEAD');
+        const length = Number(response.headers.get('content-length'));
+        const modified = Date.parse(response.headers.get('last-modified') ?? '');
+        // Build output, so created and modified are the same. Falling back to 0 rather than
+        // `Date.now()` keeps it stable - callers cache on `mtime`.
+        const mtime = Number.isNaN(modified) ? 0 : modified;
+        return {
+            type: FileType.File,
+            permissions: FilePermission.Readonly,
+            mtime,
+            ctime: mtime,
+            size: Number.isNaN(length) ? 0 : length
+        };
+    }
+
+    async readFile(resource: URI): Promise<Uint8Array> {
+        const response = await this.fetch(resource, 'GET');
+        return new Uint8Array(await response.arrayBuffer());
+    }
+
+    /**
+     * Maps the URI back to the path the build actually wrote, built through `Endpoint` so this
+     * still works when the application is deployed under a sub-path. `URI.path` is decoded, so it
+     * has to be re-encoded - otherwise a `#` or `?` in an asset name would be read as a fragment or
+     * query.
+     */
+    protected toUrl(resource: URI): string {
+        return new Endpoint({ path: `${PLUGINS_BASE_PATH}${encodePluginAssetPath(resource.path.toString())}` }).getRestUrl().toString();
+    }
+
+    protected async fetch(resource: URI, method: 'GET' | 'HEAD'): Promise<Response> {
+        if (resource.scheme !== PLUGINS_SCHEME) {
+            throw createFileSystemProviderError(`Not a plugin asset: '${resource.toString()}'`, FileSystemProviderErrorCode.FileNotFound);
+        }
+        let response: Response;
+        try {
+            response = await fetch(this.toUrl(resource), { method });
+        } catch (error) {
+            throw createFileSystemProviderError(`Could not read '${resource.toString()}': ${error.message}`, FileSystemProviderErrorCode.Unavailable);
+        }
+        if (!response.ok) {
+            // A static server 404s for directories too, but nothing asks us for one.
+            const code = response.status === 404 ? FileSystemProviderErrorCode.FileNotFound : FileSystemProviderErrorCode.Unknown;
+            throw createFileSystemProviderError(`Could not read '${resource.toString()}': ${response.status} ${response.statusText}`, code);
+        }
+        return response;
+    }
+
+    readdir(resource: URI): Promise<[string, FileType][]> {
+        throw createFileSystemProviderError('Plugin assets cannot be listed.', FileSystemProviderErrorCode.FileNotADirectory);
+    }
+
+    mkdir(resource: URI): Promise<void> {
+        throw createFileSystemProviderError('Plugin assets are read-only.', FileSystemProviderErrorCode.NoPermissions);
+    }
+
+    delete(resource: URI, opts: FileDeleteOptions): Promise<void> {
+        throw createFileSystemProviderError('Plugin assets are read-only.', FileSystemProviderErrorCode.NoPermissions);
+    }
+
+    rename(from: URI, to: URI, opts: FileOverwriteOptions): Promise<void> {
+        throw createFileSystemProviderError('Plugin assets are read-only.', FileSystemProviderErrorCode.NoPermissions);
+    }
+
+    writeFile(resource: URI, content: Uint8Array, opts: FileWriteOptions): Promise<void> {
+        throw createFileSystemProviderError('Plugin assets are read-only.', FileSystemProviderErrorCode.NoPermissions);
+    }
+}
+
+@injectable()
+export class BrowserOnlyPluginFileServiceContribution implements FileServiceContribution {
+
+    @inject(BrowserOnlyPluginFileSystemProvider)
+    protected readonly provider: BrowserOnlyPluginFileSystemProvider;
+
+    registerFileSystemProviders(service: FileService): void {
+        service.registerProvider(PLUGINS_SCHEME, this.provider);
+    }
+}

package/src/hosted/browser-only/browser-only-plugin-paths-service.spec.ts

@@ -0,0 +1,199 @@
+// *****************************************************************************
+// Copyright (C) 2026 Robert Jandow
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { enableJSDOM } from '@theia/core/lib/browser/test/jsdom';
+// `FileService` transitively imports browser modules that touch `document` at load time.
+const disableJSDOM = enableJSDOM();
+
+import { expect } from 'chai';
+import { ILogger } from '@theia/core';
+import URI from '@theia/core/lib/common/uri';
+import { MockLogger } from '@theia/core/lib/common/test/mock-logger';
+import { Container } from '@theia/core/shared/inversify';
+import { EnvVariablesServer } from '@theia/core/lib/common/env-variables';
+import { FileService } from '@theia/filesystem/lib/browser/file-service';
+import { UntitledWorkspaceService, WorkspaceFileService } from '@theia/workspace/lib/common';
+import { BrowserOnlyPluginPathsService } from './browser-only-plugin-paths-service';
+
+disableJSDOM();
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/** The directories of the browser local file system, enough of it for the path service. */
+class FakeFileService {
+    readonly directories = new Set<string>();
+    /** Lets tests assert that a cached path didn't go through {@link createFolder} again. */
+    createFolderCallCount = 0;
+
+    async createFolder(uri: URI): Promise<void> {
+        this.createFolderCallCount++;
+        for (let current = uri; !current.path.isRoot; current = current.parent) {
+            this.directories.add(current.path.toString());
+        }
+    }
+
+    async fsPath(uri: URI): Promise<string> {
+        return uri.path.toString();
+    }
+
+    async resolve(uri: URI): Promise<any> {
+        const parent = uri.path.toString();
+        const children = [...this.directories]
+            .filter(directory => new URI(directory).parent.path.toString() === parent)
+            .map(directory => ({ isDirectory: true, resource: new URI(directory) }));
+        return { isDirectory: true, resource: uri, children };
+    }
+
+    async delete(uri: URI): Promise<void> {
+        const prefix = `${uri.path.toString()}/`;
+        for (const directory of [...this.directories]) {
+            if (directory === uri.path.toString() || directory.startsWith(prefix)) {
+                this.directories.delete(directory);
+            }
+        }
+    }
+}
+
+describe('BrowserOnlyPluginPathsService', () => {
+
+    let fileService: FakeFileService;
+    let service: BrowserOnlyPluginPathsService;
+
+    function createService(): BrowserOnlyPluginPathsService {
+        const container = new Container();
+        container.bind(BrowserOnlyPluginPathsService).toSelf().inSingletonScope();
+        container.bind(ILogger).to(MockLogger);
+        container.bind(FileService).toConstantValue(fileService as any);
+        container.bind(WorkspaceFileService).toSelf().inSingletonScope();
+        container.bind(UntitledWorkspaceService).toSelf().inSingletonScope();
+        container.bind(EnvVariablesServer).toConstantValue({
+            getConfigDirUri: async () => 'file:///.theia'
+        } as EnvVariablesServer);
+        return container.get(BrowserOnlyPluginPathsService);
+    }
+
+    /** A fake session folder name for the `session`th day of December 2025, e.g. `20251203T000000`. */
+    function sessionFolderName(session: number): string {
+        const day = String(session).padStart(2, '0');
+        return `202512${day}T000000`;
+    }
+
+    function sessionFolderUri(session: number): URI {
+        return new URI(`file:///.theia/logs/${sessionFolderName(session)}/host`);
+    }
+
+    beforeEach(() => {
+        fileService = new FakeFileService();
+        service = createService();
+    });
+
+    describe('host log path', () => {
+
+        it('creates a session log folder', async () => {
+            const logPath = await service.getHostLogPath();
+
+            expect(logPath).to.match(/^\/\.theia\/logs\/\d{8}T\d{6}\/host$/);
+            expect(fileService.directories).to.include(logPath);
+        });
+
+        it('resolves the log path only once', async () => {
+            expect(await service.getHostLogPath()).to.equal(await service.getHostLogPath());
+        });
+
+        it('keeps the ten most recent session folders, the one of this session among them', async () => {
+            for (let session = 1; session <= 12; session++) {
+                await fileService.createFolder(sessionFolderUri(session));
+            }
+
+            const logPath = await service.getHostLogPath();
+
+            const sessions = sessionFolders();
+            expect(sessions).to.have.lengthOf(10);
+            expect(logPath).to.contain(sessions.find(session => !session.startsWith('/.theia/logs/202512')));
+            // the three oldest gave way to the folder of this session
+            expect(sessions).to.not.include(`/.theia/logs/${sessionFolderName(1)}`);
+            expect(sessions).to.not.include(`/.theia/logs/${sessionFolderName(3)}`);
+            expect(sessions).to.include(`/.theia/logs/${sessionFolderName(4)}`);
+            expect(sessions).to.include(`/.theia/logs/${sessionFolderName(12)}`);
+        });
+
+        it('never cleans up a folder that is not a session folder', async () => {
+            for (let session = 1; session <= 12; session++) {
+                await fileService.createFolder(sessionFolderUri(session));
+            }
+            await fileService.createFolder(new URI('file:///.theia/logs/not-a-session'));
+
+            await service.getHostLogPath();
+            // getHostLogPath() doesn't wait for the cleanup, so give it a tick to finish
+            await new Promise(resolve => setImmediate(resolve));
+
+            expect(fileService.directories).to.include('/.theia/logs/not-a-session');
+        });
+
+        function sessionFolders(): string[] {
+            return [...fileService.directories].filter(directory => /^\/\.theia\/logs\/[^/]+$/.test(directory)).sort();
+        }
+    });
+
+    describe('host storage path', () => {
+
+        it('has nowhere to store while no workspace is open', async () => {
+            expect(await service.getHostStoragePath(undefined, [])).to.be.undefined;
+        });
+
+        it('gives every workspace a storage folder of its own', async () => {
+            const one = await service.getHostStoragePath('file:///one', []);
+            const other = await service.getHostStoragePath('file:///other', []);
+
+            expect(one).to.match(/^\/\.theia\/workspace-storage\/.+$/);
+            expect(one).to.not.equal(other);
+            expect(fileService.directories).to.include(one!);
+        });
+
+        it('gives a workspace the same storage folder in every session', async () => {
+            expect(await service.getHostStoragePath('file:///one', [])).to.equal(await service.getHostStoragePath('file:///one', []));
+        });
+
+        it('keys the storage of an untitled workspace on its roots, which outlive its name', async () => {
+            const roots = ['file:///a', 'file:///b'];
+            const one = await service.getHostStoragePath('file:///.theia/workspaces/Untitled-1.theia-workspace', roots);
+            // the same roots under the name the next session gives the untitled workspace
+            const next = await service.getHostStoragePath('file:///.theia/workspaces/Untitled-2.theia-workspace', [...roots].reverse());
+
+            expect(one).to.equal(next);
+        });
+
+        it('resolves the storage path only once per workspace', async () => {
+            await service.getHostStoragePath('file:///one', []);
+            const callsAfterFirst = fileService.createFolderCallCount;
+
+            await service.getHostStoragePath('file:///one', []);
+
+            expect(fileService.createFolderCallCount).to.equal(callsAfterFirst);
+        });
+
+        it('resolves a new storage path when the roots of an untitled workspace change', async () => {
+            const workspaceUri = 'file:///.theia/workspaces/Untitled-1.theia-workspace';
+            const first = await service.getHostStoragePath(workspaceUri, ['file:///a']);
+            const callsAfterFirst = fileService.createFolderCallCount;
+
+            const second = await service.getHostStoragePath(workspaceUri, ['file:///a', 'file:///b']);
+
+            expect(second).to.not.equal(first);
+            expect(fileService.createFolderCallCount).to.be.greaterThan(callsAfterFirst);
+        });
+    });
+});

package/src/hosted/browser-only/browser-only-plugin-paths-service.ts

@@ -0,0 +1,145 @@
+// *****************************************************************************
+// Copyright (C) 2026 Robert Jandow
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { inject, injectable, named } from '@theia/core/shared/inversify';
+import { ILogger } from '@theia/core';
+import URI from '@theia/core/lib/common/uri';
+import { hashValue } from '@theia/core/lib/common/uuid';
+import { compare } from '@theia/core/lib/common/strings';
+import { EnvVariablesServer } from '@theia/core/lib/common/env-variables';
+import { FileService } from '@theia/filesystem/lib/browser/file-service';
+import { UntitledWorkspaceService } from '@theia/workspace/lib/common';
+import { PluginPathsService } from '../../main/common/plugin-paths-protocol';
+import { PluginPaths } from '../../main/common/paths/const';
+
+/** Session folder name, e.g. `20181205T093828`, same format as the backend uses. */
+const SESSION_TIMESTAMP_PATTERN = /^\d{8}T\d{6}$/;
+
+/**
+ * Resolves plugin log and storage locations for a browser-only application, under the config
+ * directory, which lives on the same (browser-local) file system as the workspace.
+ */
+@injectable()
+export class BrowserOnlyPluginPathsService implements PluginPathsService {
+
+    @inject(ILogger) @named('plugin-ext:BrowserOnlyPluginPathsService')
+    protected readonly logger: ILogger;
+
+    @inject(EnvVariablesServer)
+    protected readonly envServer: EnvVariablesServer;
+
+    @inject(FileService)
+    protected readonly fileService: FileService;
+
+    @inject(UntitledWorkspaceService)
+    protected readonly untitledWorkspaceService: UntitledWorkspaceService;
+
+    protected hostLogPath: Promise<string> | undefined;
+
+    getHostLogPath(): Promise<string> {
+        // cached: unlike the backend, where each call creates a new session folder, here one tab
+        // runs one session, and the plugin host may ask again on a later load cycle
+        return this.hostLogPath ??= this.resolveHostLogPath();
+    }
+
+    protected async resolveHostLogPath(): Promise<string> {
+        const configDirUri = new URI(await this.envServer.getConfigDirUri());
+        const logsDirUri = configDirUri.resolve(PluginPaths.PLUGINS_LOGS_DIR);
+        const hostLogPath = await this.ensureDirectory(logsDirUri.resolve(this.generateTimeFolderName()).resolve('host'));
+        // as on the backend, we never wait for the cleanup
+        this.cleanUpOldLogs(logsDirUri).catch(error => this.logger.error('Failed to clean up old plugin log folders:', error));
+        return hostLogPath;
+    }
+
+    /**
+     * Resolving re-hashes the workspace id and hits {@link FileService.createFolder}, and the plugin
+     * server asks for this on every workspace storage read/write. The roots are part of the key
+     * because an untitled workspace's id is derived from them.
+     */
+    protected readonly hostStoragePaths = new Map<string, Promise<string>>();
+
+    async getHostStoragePath(workspaceUri: string | undefined, rootUris: string[]): Promise<string | undefined> {
+        if (!workspaceUri) {
+            // no workspace, no place to store workspace state - same as the backend
+            return undefined;
+        }
+        // '\n' cannot appear in a URI, so it is safe as a separator between the workspace URI and its roots
+        const cacheKey = `${workspaceUri}\n${[...rootUris].sort().join('\n')}`;
+        let hostStoragePath = this.hostStoragePaths.get(cacheKey);
+        if (!hostStoragePath) {
+            hostStoragePath = this.resolveHostStoragePath(workspaceUri, rootUris);
+            this.hostStoragePaths.set(cacheKey, hostStoragePath);
+            // a transient failure (e.g. a flaky file system call) shouldn't poison the cache forever
+            hostStoragePath.catch(() => this.hostStoragePaths.delete(cacheKey));
+        }
+        return hostStoragePath;
+    }
+
+    protected async resolveHostStoragePath(workspaceUri: string, rootUris: string[]): Promise<string> {
+        const configDirUri = new URI(await this.envServer.getConfigDirUri());
+        const workspaceId = await this.buildWorkspaceId(configDirUri, workspaceUri, rootUris);
+        return this.ensureDirectory(configDirUri.resolve(PluginPaths.PLUGINS_WORKSPACE_STORAGE_DIR).resolve(workspaceId));
+    }
+
+    protected async buildWorkspaceId(configDirUri: URI, workspaceUri: string, rootUris: string[]): Promise<string> {
+        if (this.untitledWorkspaceService.isUntitledWorkspace(new URI(workspaceUri), configDirUri)) {
+            // an untitled workspace is named anew in every session, so key its storage on the roots instead
+            return hashValue([...rootUris].sort().join(','));
+        }
+        return hashValue(workspaceUri);
+    }
+
+    /**
+     * Generate time folder name in format: YYYYMMDDTHHMMSS, for example: 20181205T093828
+     */
+    protected generateTimeFolderName(): string {
+        const timeStamp = new Date().toISOString().replace(/[-:]|(\..*)/g, '');
+        // Helps ensure our timestamp generation logic is "valid".
+        // Changes to the timestamp structure may break old logs deletion logic.
+        if (!SESSION_TIMESTAMP_PATTERN.test(timeStamp)) {
+            this.logger.error(`Generated log folder name: "${timeStamp}" does not match expected pattern: ${SESSION_TIMESTAMP_PATTERN}`);
+        }
+        return timeStamp;
+    }
+
+    /**
+     * Keeps only the most recent {@link PluginPaths.DEFAULT_PLUGIN_MAX_SESSION_LOGS_FOLDERS}
+     * session folders under `logsDirUri`, so reloading doesn't fill up browser storage.
+     */
+    protected async cleanUpOldLogs(logsDirUri: URI): Promise<void> {
+        const logsDir = await this.fileService.resolve(logsDirUri);
+        const sessionDirs = (logsDir.children ?? [])
+            // we never clean a folder that is not a Theia logs session folder, even if it
+            // does appear under `logsDirUri`
+            .filter(child => child.isDirectory && SESSION_TIMESTAMP_PATTERN.test(child.resource.path.base))
+            .map(child => child.resource)
+            // newest first, so the oldest ones get cut off. Ordinal comparison, not
+            // localeCompare - the format is fixed ASCII, and locale-aware sorting could order
+            // it differently depending on the user's locale
+            .sort((one, other) => compare(other.path.base, one.path.base));
+        const oldSessionDirs = sessionDirs.slice(PluginPaths.DEFAULT_PLUGIN_MAX_SESSION_LOGS_FOLDERS);
+        await Promise.all(oldSessionDirs.map(uri => this.fileService.delete(uri, { fromUserGesture: false, recursive: true })));
+    }
+
+    /**
+     * Creates `uri` as a directory (fine if it already exists) and returns its path. Plugins get
+     * the path rather than the URI, e.g. as `ExtensionContext.storagePath`.
+     */
+    protected async ensureDirectory(uri: URI): Promise<string> {
+        await this.fileService.createFolder(uri, { fromUserGesture: false });
+        return this.fileService.fsPath(uri);
+    }
+}