@theia/preferences 1.76.0-next.6 → 1.76.0

package/src/common/cli-preferences.spec.ts

@@ -0,0 +1,73 @@
+// *****************************************************************************
+// Copyright (C) 2026 EclipseSource GmbH 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 { CliPreferenceEntry } from './cli-preferences';
+
+describe('CliPreferenceEntry.parse', () => {
+
+    it('parses a KEY=JSONVALUE assignment', () => {
+        expect(CliPreferenceEntry.parse('editor.fontSize=14')).to.deep.equal(['editor.fontSize', 14]);
+    });
+
+    it('parses boolean and string JSON values', () => {
+        expect(CliPreferenceEntry.parse('foo.enabled=true')).to.deep.equal(['foo.enabled', true]);
+        expect(CliPreferenceEntry.parse('foo.label="hello"')).to.deep.equal(['foo.label', 'hello']);
+    });
+
+    it('keeps "=" characters that are part of the value', () => {
+        expect(CliPreferenceEntry.parse('foo.expr="a=b"')).to.deep.equal(['foo.expr', 'a=b']);
+    });
+
+    it('decodes a base64-encoded value', () => {
+        // base64 of the JSON value `42`
+        expect(CliPreferenceEntry.parse('foo.num=base64:NDI=')).to.deep.equal(['foo.num', 42]);
+    });
+
+    it('returns undefined when there is no key', () => {
+        expect(CliPreferenceEntry.parse('=1')).to.be.undefined;
+    });
+
+    it('returns undefined when there is no "="', () => {
+        expect(CliPreferenceEntry.parse('noequals')).to.be.undefined;
+    });
+
+    it('returns undefined for an invalid JSON value', () => {
+        expect(CliPreferenceEntry.parse('foo.bar=not json')).to.be.undefined;
+    });
+
+    describe('parseAll', () => {
+        it('parses and filters a list, dropping invalid entries', () => {
+            const result = CliPreferenceEntry.parseAll(['a=1', 'bad', 'b="x"']);
+            expect(result).to.deep.equal([['a', 1], ['b', 'x']]);
+        });
+    });
+
+    describe('toArg', () => {
+        it('formats an entry as a base64-encoded CLI argument', () => {
+            // base64 of the JSON value `42`
+            expect(CliPreferenceEntry.toArg('session-preference', ['foo.num', 42])).to.equal('--session-preference=foo.num=base64:NDI=');
+        });
+
+        it('round-trips a value with shell-special characters through toArg + parse', () => {
+            const entry: [string, unknown] = ['foo.expr', '$HOME && "quoted"'];
+            const arg = CliPreferenceEntry.toArg('session-preference', entry);
+            // The value part of `--session-preference=<value>` must parse back to the original entry.
+            const value = arg.substring('--session-preference='.length);
+            expect(CliPreferenceEntry.parse(value)).to.deep.equal(entry);
+        });
+    });
+});

package/src/common/cli-preferences.ts

@@ -21,3 +21,78 @@ export interface CliPreferences {
     getPreferences(): Promise<[string, unknown][]>;
     getSessionPreferences(): Promise<[string, unknown][]>;
 }
+
+export namespace CliPreferenceEntry {
+
+    /**
+     * Sink for warnings about malformed entries. Callers running in an Inversify context should
+     * pass their named `ILogger`, since these helpers live in `common` and cannot inject one
+     * themselves. Defaults to `console.warn`.
+     */
+    export type WarningSink = (message: string) => void;
+
+    const defaultWarn: WarningSink = message => console.warn(message);
+
+    /**
+     * Parses a single `KEY=JSONVALUE` preference assignment as accepted by `--set-preference`
+     * and `--session-preference`. The value may be `base64:`-prefixed (used when forwarding
+     * values that must survive shell/URL transport intact). Returns `undefined` (after logging a
+     * warning to {@link warn}) when the entry has no key or the value is not valid JSON.
+     */
+    export function parse(entry: string, warn: WarningSink = defaultWarn): [string, unknown] | undefined {
+        const firstEqualIndex = entry.indexOf('=');
+        if (firstEqualIndex <= 0) {
+            warn(`Ignoring preference CLI argument "${entry}": expected KEY=JSONVALUE.`);
+            return undefined;
+        }
+        const rawValue = entry.substring(firstEqualIndex + 1);
+        try {
+            // Decoding happens inside the `try` so that a malformed `base64:` payload is reported
+            // like any other invalid value instead of throwing out of `parse`.
+            const value = rawValue.startsWith('base64:') ? decodeBase64(rawValue.substring('base64:'.length)) : rawValue;
+            return [entry.substring(0, firstEqualIndex), JSON.parse(value)];
+        } catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            warn(`Ignoring preference CLI argument "${entry}": value is not valid JSON (${reason}).`);
+            return undefined;
+        }
+    }
+
+    /**
+     * Formats a preference entry as a CLI argument of the form
+     * `--<optionName>=<key>=base64:<base64(JSON(value))>`, the inverse of {@link parse}.
+     *
+     * The value is base64-encoded so it survives shell/URL transport intact (e.g. when the
+     * argument is passed to a remote backend over an SSH command line).
+     */
+    export function toArg(optionName: string, [key, value]: [string, unknown]): string {
+        return `--${optionName}=${key}=base64:${encodeBase64(JSON.stringify(value))}`;
+    }
+
+    /**
+     * Parses a list of `KEY=JSONVALUE` assignments, dropping any invalid entries and reporting
+     * them to {@link warn}.
+     */
+    export function parseAll(entries: readonly string[], warn: WarningSink = defaultWarn): [string, unknown][] {
+        const result: [string, unknown][] = [];
+        for (const entry of entries) {
+            const parsed = parse(entry, warn);
+            if (parsed) {
+                result.push(parsed);
+            }
+        }
+        return result;
+    }
+
+    // `Buffer` is available on the backend and is polyfilled into the frontend bundle by the
+    // esbuild generator, so a single implementation covers both. It also handles UTF-8 directly,
+    // unlike `atob`/`btoa`, which only deal in binary strings.
+
+    function decodeBase64(value: string): string {
+        return Buffer.from(value, 'base64').toString('utf-8');
+    }
+
+    function encodeBase64(value: string): string {
+        return Buffer.from(value, 'utf-8').toString('base64');
+    }
+}

package/src/node/preference-cli-contribution.ts

@@ -18,7 +18,7 @@ import { injectable, inject, named } from '@theia/core/shared/inversify';
 import { Argv } from '@theia/core/shared/yargs';
 import { CliContribution } from '@theia/core/lib/node/cli';
 import { RemoteCliContext, RemoteCliContribution } from '@theia/core/lib/node/remote/remote-cli-contribution';
-import { CliPreferences } from '../common/cli-preferences';
+import { CliPreferences, CliPreferenceEntry } from '../common/cli-preferences';
 import { ILogger } from '@theia/core';
 
 @injectable()
@@ -52,23 +52,7 @@ export class PreferenceCliContribution implements CliContribution, CliPreference
 
     protected parseInto(raw: unknown, target: [string, unknown][]): void {
         const entries: string[] = raw instanceof Array ? raw : [raw as string];
-        for (const entry of entries) {
-            const firstEqualIndex = entry.indexOf('=');
-            if (firstEqualIndex <= 0) {
-                this.logger.warn(`Ignoring preference CLI argument "${entry}": expected KEY=JSONVALUE.`);
-                continue;
-            }
-            let rawValue = entry.substring(firstEqualIndex + 1);
-            if (rawValue.startsWith('base64:')) {
-                rawValue = Buffer.from(rawValue.substring('base64:'.length), 'base64').toString('utf-8');
-            }
-            try {
-                target.push([entry.substring(0, firstEqualIndex), JSON.parse(rawValue)]);
-            } catch (e) {
-                const reason = e instanceof Error ? e.message : String(e);
-                this.logger.warn(`Ignoring preference CLI argument "${entry}": value is not valid JSON (${reason}).`);
-            }
-        }
+        target.push(...CliPreferenceEntry.parseAll(entries, message => this.logger.warn(message)));
     }
 
     async getPreferences(): Promise<[string, unknown][]> {
@@ -85,10 +69,7 @@ export class PreferenceCliContribution implements CliContribution, CliPreference
      * shell argument parsing intact.
      */
     enhanceArgs(_context: RemoteCliContext): string[] {
-        return this.sessionPreferences.map(([key, value]) => {
-            const encoded = Buffer.from(JSON.stringify(value), 'utf-8').toString('base64');
-            return `--session-preference=${key}=base64:${encoded}`;
-        });
+        return this.sessionPreferences.map(entry => CliPreferenceEntry.toArg('session-preference', entry));
     }
 
 }