@theia/plugin-utils 1.75.0-next.28

package/src/common/manifest-types.ts

@@ -0,0 +1,126 @@
+// *****************************************************************************
+// Copyright (C) 2026 Maksim Kachurin and others.
+//
+// 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 { isObject } from './utils';
+import type { NormalizedPluginContribution, PluginManifestContribution } from './contribution-types';
+
+export const PLUGIN_HOST_BACKEND = 'main' as const;
+
+/** Whether a plugin is installed by the system or by a user. */
+export enum PluginType {
+    System = 0,
+    User = 1
+}
+
+/** Same shape as `PluginPackage.capabilities` in `plugin-protocol.ts`. */
+export interface PluginPackageCapabilities {
+    untrustedWorkspaces?: {
+        supported: boolean | 'limited';
+        description?: string;
+        restrictedConfigurations?: string[];
+    };
+}
+
+/**
+ * VS Code / Theia extension `package.json` manifest.
+ */
+export interface PluginManifest {
+    name: string;
+    version: string;
+    publisher?: string;
+    displayName?: string;
+    description?: string;
+    l10n?: string;
+    packagePath: string;
+    packageUri?: string;
+    engines?: Record<string, string>;
+    theiaPlugin?: { frontend?: string; backend?: string; headless?: string };
+    main?: string;
+    browser?: string;
+    extensionKind?: Array<'ui' | 'workspace'>;
+    icon?: string;
+    type?: 'module' | 'commonjs';
+    extensionDependencies?: string[];
+    extensionPack?: string[];
+    capabilities?: PluginPackageCapabilities;
+    /** Raw `contributes` section from `package.json` before normalization. */
+    contributes?: PluginManifestContribution;
+    activationEvents?: string[];
+}
+
+export function rawContributes(manifest: Pick<PluginManifest, 'contributes'>): PluginManifestContribution {
+    return isObject(manifest.contributes) ? manifest.contributes as PluginManifestContribution : {};
+}
+
+export interface PluginEntryPoint {
+    frontend?: string;
+    backend?: string;
+    headless?: string;
+}
+
+/** Plugin model populated from `package.json`. */
+export interface PluginModel {
+    id: string;
+    name: string;
+    publisher: string;
+    version: string;
+    displayName: string;
+    description: string;
+    engine: { type: string; version: string };
+    entryPoint: PluginEntryPoint;
+    packageUri: string;
+    /**
+     * @deprecated since 1.1.0 - because it lead to problems with getting a relative path
+     * needed by Icon Themes to correctly load Fonts, use packageUri instead.
+     */
+    packagePath: string;
+    iconUrl?: string;
+    l10n?: string;
+    readmeUrl?: string;
+    licenseUrl?: string;
+    untrustedWorkspacesSupport?: boolean | 'limited';
+}
+
+export interface PluginLifecycle {
+    startMethod: string;
+    stopMethod: string;
+    /** Frontend module name; the frontend plugin should expose this name. */
+    frontendModuleName?: string;
+    /** Script run before the frontend plugin is loaded. */
+    frontendInitPath?: string;
+    /** Script run before the backend plugin is loaded. */
+    backendInitPath?: string;
+}
+
+export interface PluginMetadata {
+    /** Plugin host id used for RPC routing (e.g. {@link PLUGIN_HOST_BACKEND}). */
+    host: string;
+    model: PluginModel;
+    lifecycle: PluginLifecycle;
+    outOfSync: boolean;
+    /** Set when the plugin is loaded from a development workspace (e.g. plugin-dev). */
+    isUnderDevelopment?: boolean;
+}
+
+/**
+ * Deployed plugin descriptor (runtime + browser-only `list.json`).
+ */
+export interface DeployedPlugin<TContributes = NormalizedPluginContribution> {
+    /** Defaults to {@link PluginType.System}. */
+    type?: PluginType;
+    metadata: PluginMetadata;
+    contributes?: TContributes;
+}

package/src/common/package-nls.spec.ts

@@ -0,0 +1,122 @@
+// *****************************************************************************
+// Copyright (C) 2026 Maksim Kachurin and others.
+//
+// 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 { expect } from 'chai';
+import * as fs from 'fs-extra';
+import * as os from 'os';
+import * as path from 'path';
+import { coerceLocalizations, localizePackage, localizeWithResolver } from './package-nls';
+import { loadPackageTranslations } from '../node/package-nls';
+
+describe('package-nls', () => {
+
+    describe('coerceLocalizations', () => {
+        it('passes through string values', () => {
+            expect(coerceLocalizations({ key: 'value' })).to.deep.equal({ key: 'value' });
+        });
+
+        it('extracts message from LocalizeInfo objects', () => {
+            expect(coerceLocalizations({ key: { message: 'Hello', comment: 'greeting' } })).to.deep.equal({ key: 'Hello' });
+        });
+
+        it('marks invalid values explicitly', () => {
+            expect(coerceLocalizations({ key: 42 as unknown as string })).to.deep.equal({ key: 'INVALID TRANSLATION VALUE' });
+        });
+    });
+
+    describe('localizeWithResolver', () => {
+        it('localizes nested structures and leaves unknown keys unchanged', () => {
+            const localized = localizeWithResolver(
+                {
+                    title: '%title.key%',
+                    nested: [{ label: '%nested.key%' }],
+                    plain: 'unchanged'
+                },
+                key => (key === 'title.key' ? 'Title' : undefined)
+            );
+            expect(localized).to.deep.equal({
+                title: 'Title',
+                nested: [{ label: '%nested.key%' }],
+                plain: 'unchanged'
+            });
+        });
+
+        it('keeps %key% when resolve returns undefined or an empty string', () => {
+            expect(localizeWithResolver('%missing.key%', () => undefined)).to.equal('%missing.key%');
+            expect(localizeWithResolver('%empty.key%', () => '')).to.equal('%empty.key%');
+        });
+
+        it('ignores strings that are not %key% placeholders', () => {
+            expect(localizeWithResolver('%not-closed', () => 'x')).to.equal('%not-closed');
+            expect(localizeWithResolver('100%', () => 'x')).to.equal('100%');
+        });
+    });
+
+    describe('localizePackage', () => {
+        it('uses translation bundle before default bundle', () => {
+            const localized = localizePackage(
+                { displayName: '%name.key%' },
+                {
+                    translation: { 'name.key': 'Translated' },
+                    default: { 'name.key': 'Default' }
+                },
+                () => 'callback-should-not-run'
+            );
+            expect(localized).to.deep.equal({ displayName: 'Translated' });
+        });
+
+        it('invokes callback for default bundle when translation is missing', () => {
+            const localized = localizePackage(
+                { displayName: '%name.key%' },
+                { default: { 'name.key': 'Default value' } },
+                (_key, defaultValue) => `from-default:${defaultValue}`
+            );
+            expect(localized).to.deep.equal({ displayName: 'from-default:Default value' });
+        });
+    });
+
+    describe('loadPackageTranslations', () => {
+        let pluginRoot: string;
+
+        beforeEach(async () => {
+            pluginRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'package-nls-load-'));
+        });
+
+        afterEach(async () => {
+            await fs.remove(pluginRoot);
+        });
+
+        it('returns an empty object when package.nls.json is missing', async () => {
+            expect(await loadPackageTranslations(pluginRoot)).to.deep.equal({});
+        });
+
+        it('loads the default bundle without a locale', async () => {
+            await fs.writeJson(path.join(pluginRoot, 'package.nls.json'), { 'display.name': 'Sample' });
+            expect(await loadPackageTranslations(pluginRoot)).to.deep.equal({
+                default: { 'display.name': 'Sample' }
+            });
+        });
+
+        it('loads locale-specific translations when present', async () => {
+            await fs.writeJson(path.join(pluginRoot, 'package.nls.json'), { 'display.name': 'Sample' });
+            await fs.writeJson(path.join(pluginRoot, 'package.nls.de.json'), { 'display.name': 'Beispiel' });
+            expect(await loadPackageTranslations(pluginRoot, 'de')).to.deep.equal({
+                default: { 'display.name': 'Sample' },
+                translation: { 'display.name': 'Beispiel' }
+            });
+        });
+    });
+});

package/src/common/package-nls.ts

@@ -0,0 +1,95 @@
+// *****************************************************************************
+// Copyright (C) 2021 TypeFox and others.
+//
+// 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 { isObject } from './utils';
+
+export interface PackageTranslation {
+    translation?: Record<string, string>;
+    default?: Record<string, string>;
+}
+
+interface LocalizeInfo {
+    message: string;
+    comment?: string;
+}
+
+function isLocalizeInfo(obj: unknown): obj is LocalizeInfo {
+    return isObject(obj) && 'message' in obj && typeof (obj as { message?: unknown }).message === 'string';
+}
+
+export function coerceLocalizations(translations: Record<string, string | LocalizeInfo>): Record<string, string> {
+    const result: Record<string, string> = {};
+    for (const [key, value] of Object.entries(translations)) {
+        if (typeof value === 'string') {
+            result[key] = value;
+        } else if (isLocalizeInfo(value)) {
+            result[key] = value.message;
+        } else {
+            // Only strings or LocalizeInfo values are valid
+            result[key] = 'INVALID TRANSLATION VALUE';
+        }
+    }
+    return result;
+}
+
+/**
+ * Recursively walks `value` and replaces strings matching `%key%` with the result of `resolve(key)`.
+ * If `resolve(key)` returns `undefined` or an empty string, the original `%key%` is kept
+ * (same as the former worker `localize`: `translations[key] || value`).
+ */
+export function localizeWithResolver<T>(value: T, resolve: (key: string) => string | undefined): T {
+    if (typeof value === 'string') {
+        if (value.length > 2 && value.startsWith('%') && value.endsWith('%')) {
+            const replaced = resolve(value.slice(1, -1));
+            return (replaced || value) as T;
+        }
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map(item => localizeWithResolver(item, resolve)) as T;
+    }
+    if (isObject(value)) {
+        const result: Record<string, unknown> = {};
+        for (const [name, item] of Object.entries(value)) {
+            result[name] = localizeWithResolver(item, resolve);
+        }
+        return result as T;
+    }
+    return value;
+}
+
+export type LocalizePackageCallback = (key: string, defaultValue: string) => string;
+
+/**
+ * Recursively replaces %key% strings in value with translations.
+ * callback is used when only default (package.nls.json) exists; e.g. backend passes
+ * Theia's Localization.localize for fallback, build-time can use (_, d) => d.
+ */
+export function localizePackage<T>(
+    value: T,
+    translations: PackageTranslation,
+    callback: LocalizePackageCallback
+): T {
+    return localizeWithResolver(value, key => {
+        if (translations.translation && key in translations.translation) {
+            return translations.translation[key];
+        }
+        if (translations.default && key in translations.default) {
+            return callback(key, translations.default[key]);
+        }
+        return undefined;
+    });
+}

package/src/common/plugin-activation-events.spec.ts

@@ -0,0 +1,104 @@
+// *****************************************************************************
+// Copyright (C) 2026 Maksim Kachurin and others.
+//
+// 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 { expect } from 'chai';
+import { updateActivationEvents } from './plugin-activation-events';
+import type { PluginManifest } from './manifest-types';
+
+function manifest(partial: Pick<PluginManifest, 'contributes' | 'activationEvents'>): Pick<PluginManifest, 'contributes' | 'activationEvents'> {
+    return {
+        activationEvents: partial.activationEvents ? [...partial.activationEvents] : undefined,
+        contributes: partial.contributes
+    };
+}
+
+describe('plugin-activation-events', () => {
+
+    it('no-ops when contributes is missing or invalid', () => {
+        const empty = manifest({});
+        updateActivationEvents(empty);
+        expect(empty.activationEvents).to.equal(undefined);
+
+        const invalid = manifest({ contributes: 'bad' as unknown as PluginManifest['contributes'] });
+        updateActivationEvents(invalid);
+        expect(invalid.activationEvents).to.equal(undefined);
+    });
+
+    it('derives activation events from contributed commands and languages', () => {
+        const pkg = manifest({
+            activationEvents: ['onStartupFinished'],
+            contributes: {
+                commands: [{ command: 'sample.run', title: 'Run' }],
+                languages: [{ id: 'typescript', extensions: ['.ts'] }]
+            }
+        });
+
+        updateActivationEvents(pkg);
+
+        expect(pkg.activationEvents).to.include.members([
+            'onStartupFinished',
+            'onCommand:sample.run',
+            'onLanguage:typescript'
+        ]);
+    });
+
+    it('derives activation events from views, custom editors, auth, and notebooks', () => {
+        const pkg = manifest({
+            contributes: {
+                views: {
+                    explorer: [{ id: 'sample.view', name: 'Sample' }]
+                },
+                customEditors: [{ viewType: 'sample.editor', displayName: 'Editor', selector: [] }],
+                authentication: [{ id: 'github', label: 'GitHub' }],
+                notebooks: [{ type: 'sample-notebook', displayName: 'Notebook' }]
+            }
+        });
+
+        updateActivationEvents(pkg);
+
+        expect(pkg.activationEvents).to.include.members([
+            'onView:sample.view',
+            'onCustomEditor:sample.editor',
+            'onAuthenticationRequest:github',
+            'onNotebookSerializer:sample-notebook'
+        ]);
+    });
+
+    it('supports a single command object instead of an array', () => {
+        const pkg = manifest({
+            contributes: {
+                commands: { command: 'solo.run', title: 'Solo' } as unknown as { command: string; title: string }
+            }
+        });
+
+        updateActivationEvents(pkg);
+
+        expect(pkg.activationEvents).to.include('onCommand:solo.run');
+    });
+
+    it('ignores malformed views contributions that are not plain objects', () => {
+        const pkg = manifest({
+            contributes: {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                views: 'not-an-object' as any
+            }
+        });
+
+        updateActivationEvents(pkg);
+
+        expect(pkg.activationEvents ?? []).to.be.empty;
+    });
+});

package/src/common/plugin-activation-events.ts

@@ -0,0 +1,102 @@
+// *****************************************************************************
+// Copyright (C) 2023 TypeFox and others.
+//
+// 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 { flatten, isObject, isStringArray } from './utils';
+import { rawContributes, type PluginManifest } from './manifest-types';
+
+/**
+ * Most activation events can be automatically deduced from the package manifest.
+ * This function will update the manifest based on the plugin contributions.
+ */
+export function updateActivationEvents(manifest: Pick<PluginManifest, 'contributes' | 'activationEvents'>): void {
+    if (!isObject(manifest) || !isObject(manifest.contributes) || !manifest.contributes) {
+        return;
+    }
+
+    const activationEvents = new Set(isStringArray(manifest.activationEvents) ? manifest.activationEvents : []);
+    const contributes = rawContributes(manifest);
+
+    if (contributes.commands) {
+        const commands = Array.isArray(contributes.commands) ? contributes.commands : [contributes.commands];
+        updateCommandsContributions(commands, activationEvents);
+    }
+    if (isObject(contributes.views) && !Array.isArray(contributes.views)) {
+        const views = flatten(Object.values(contributes.views));
+        updateViewsContribution(views, activationEvents);
+    }
+    if (Array.isArray(contributes.customEditors)) {
+        updateCustomEditorsContribution(contributes.customEditors, activationEvents);
+    }
+    if (Array.isArray(contributes.authentication)) {
+        updateAuthenticationProviderContributions(contributes.authentication, activationEvents);
+    }
+    if (Array.isArray(contributes.languages)) {
+        updateLanguageContributions(contributes.languages, activationEvents);
+    }
+    if (Array.isArray(contributes.notebooks)) {
+        updateNotebookContributions(contributes.notebooks, activationEvents);
+    }
+
+    manifest.activationEvents = Array.from(activationEvents);
+}
+
+function updateViewsContribution(views: unknown[], activationEvents: Set<string>): void {
+    for (const view of views) {
+        if (isObject(view) && typeof view.id === 'string') {
+            activationEvents.add(`onView:${view.id}`);
+        }
+    }
+}
+
+function updateCustomEditorsContribution(customEditors: unknown[], activationEvents: Set<string>): void {
+    for (const customEditor of customEditors) {
+        if (isObject(customEditor) && typeof customEditor.viewType === 'string') {
+            activationEvents.add(`onCustomEditor:${customEditor.viewType}`);
+        }
+    }
+}
+
+function updateCommandsContributions(commands: unknown[], activationEvents: Set<string>): void {
+    for (const command of commands) {
+        if (isObject(command) && typeof command.command === 'string') {
+            activationEvents.add(`onCommand:${command.command}`);
+        }
+    }
+}
+
+function updateAuthenticationProviderContributions(authProviders: unknown[], activationEvents: Set<string>): void {
+    for (const authProvider of authProviders) {
+        if (isObject(authProvider) && typeof authProvider.id === 'string') {
+            activationEvents.add(`onAuthenticationRequest:${authProvider.id}`);
+        }
+    }
+}
+
+function updateLanguageContributions(languages: unknown[], activationEvents: Set<string>): void {
+    for (const language of languages) {
+        if (isObject(language) && typeof language.id === 'string') {
+            activationEvents.add(`onLanguage:${language.id}`);
+        }
+    }
+}
+
+function updateNotebookContributions(notebooks: unknown[], activationEvents: Set<string>): void {
+    for (const notebook of notebooks) {
+        if (isObject(notebook) && typeof notebook.type === 'string') {
+            activationEvents.add(`onNotebookSerializer:${notebook.type}`);
+        }
+    }
+}

package/src/common/plugin-manifest.spec.ts

@@ -0,0 +1,94 @@
+// *****************************************************************************
+// Copyright (C) 2026 Maksim Kachurin and others.
+//
+// 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 { expect } from 'chai';
+import { UNPUBLISHED, VSCODE_BUILTIN_NAME_PREFIX } from './constants';
+import { prepareLoadedManifest, stripVscodeBuiltinNamePrefix } from './plugin-manifest';
+import { loadManifest } from '../node/plugin-manifest';
+import type { PluginManifest } from './manifest-types';
+import * as fs from 'fs-extra';
+import * as os from 'os';
+import * as path from 'path';
+
+describe('plugin-manifest', () => {
+
+    describe('stripVscodeBuiltinNamePrefix', () => {
+        it('removes the vscode builtin prefix from package names', () => {
+            const manifest: Pick<PluginManifest, 'name'> = {
+                name: `${VSCODE_BUILTIN_NAME_PREFIX}json`
+            };
+            stripVscodeBuiltinNamePrefix(manifest);
+            expect(manifest.name).to.equal('json');
+        });
+    });
+
+    describe('prepareLoadedManifest', () => {
+        it('defaults publisher and derives activation events', () => {
+            const manifest = prepareLoadedManifest({
+                name: 'sample',
+                version: '1.0.0',
+                packagePath: '/tmp/sample',
+                contributes: {
+                    commands: [{ command: 'sample.run', title: 'Run' }]
+                }
+            } as PluginManifest);
+
+            expect(manifest.publisher).to.equal(UNPUBLISHED);
+            expect(manifest.activationEvents).to.include('onCommand:sample.run');
+        });
+
+        it('can skip activation event derivation', () => {
+            const manifest = prepareLoadedManifest({
+                name: 'sample',
+                version: '1.0.0',
+                packagePath: '/tmp/sample',
+                contributes: {
+                    commands: [{ command: 'sample.run', title: 'Run' }]
+                }
+            } as PluginManifest, { updateActivationEvents: false });
+
+            expect(manifest.activationEvents).to.equal(undefined);
+        });
+    });
+
+    describe('loadManifest', () => {
+        let pluginRoot: string;
+
+        beforeEach(async () => {
+            pluginRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'plugin-manifest-'));
+        });
+
+        afterEach(async () => {
+            await fs.remove(pluginRoot);
+        });
+
+        it('reads and prepares package.json from disk', async () => {
+            await fs.writeJson(path.join(pluginRoot, 'package.json'), {
+                name: `${VSCODE_BUILTIN_NAME_PREFIX}json`,
+                version: '1.0.0',
+                contributes: {
+                    commands: [{ command: 'json.format', title: 'Format JSON' }]
+                }
+            });
+
+            const manifest = await loadManifest(pluginRoot);
+
+            expect(manifest.name).to.equal('json');
+            expect(manifest.publisher).to.equal(UNPUBLISHED);
+            expect(manifest.activationEvents).to.include('onCommand:json.format');
+        });
+    });
+});