@vscode/webview-themes 0.0.0-stage → 0.0.2-1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,304 @@
-# Temporary Holding Version
+# @vscode/webview-themes
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Actual VS Code webview colors for Component Explorer fixtures. The browser
+runtime has **no dependencies**, works with React 16 or newer, plain DOM,
+Webpack and Vite, and does not require VS Code or network access.
+
+The checked-in theme data includes all built-in VS Code color themes and all nine
+variants of `GitHub.github-vscode-theme`, including both high-contrast variants.
+These are **resolved snapshots**, not theme JSON files layered over a guessed
+palette. Each snapshot includes the CSS variables VS Code actually injects,
+including default/derived colors and font settings.
+
+## Data layout
+
+The package ships a small JSON index plus one JSON and one CSS file per theme:
+
+```text
+@vscode/webview-themes/index.json
+@vscode/webview-themes/themes/github-github-vscode-theme-dark-default.json
+@vscode/webview-themes/themes/github-github-vscode-theme-dark-default.css
+```
+
+The index contains `schemaVersion`, build provenance in `source`, and a `themes`
+array. Each entry has `id`, `label`, `settingsId`, `extensionId`, `themePath`,
+`light`, `highContrast`, `className`, `json`, and `css`. Asset paths are relative
+to the physical index file in `themes/`. There are no palettes in the index:
+a picker can list themes without loading every theme's variables.
+
+Each theme JSON has this shape:
+
+```ts
+interface Theme {
+    readonly id: string;
+    readonly label: string;
+    readonly settingsId?: string;
+    readonly light: boolean;
+    readonly highContrast: boolean;
+    readonly cssVariableValues: Readonly<Record<string, string>>;
+}
+```
+
+Generated themes always have `settingsId`, the original VS Code theme selector.
+`id` is an extension-qualified slug derived from the extension ID and theme asset
+path, not the display label. For example, `GitHub.github-vscode-theme` and
+`themes/dark-default.json` produce `github-github-vscode-theme-dark-default`.
+Renaming/localizing a label does not rename the files. Slug collisions fail
+generation explicitly instead of overwriting another theme.
+
+| Theme kind | `light` | `highContrast` |
+| --- | --- | --- |
+| Dark | false | false |
+| Light | true | false |
+| High-contrast dark | false | true |
+| High-contrast light | true | true |
+
+Variable keys include the full CSS name, such as `--vscode-editor-background`.
+`getThemeKind(theme)` derives the corresponding VS Code class name from the two
+booleans; a redundant kind string is not stored in the per-theme files.
+
+## Fixtures with the JS controller
+
+```ts
+import { applyTheme, parseTheme } from '@vscode/webview-themes';
+import themeData from '@vscode/webview-themes/themes/github-github-vscode-theme-dark-default.json';
+
+// Inside a fixture render(container, context):
+const controller = context.addDisposable(applyTheme(container, parseTheme(themeData)));
+```
+
+Import `@vscode/webview-themes/index.json` to populate a picker. The application
+chooses how to load selected JSON files (static imports, bundler dynamic imports,
+or fetching assets it serves); the runtime does not fetch or eagerly import data.
+`controller.setTheme(nextTheme)` switches without remounting the component.
+Disposal restores the previous styles, classes and attributes. Overlapping
+controllers on the same target are rejected.
+
+The wrapper sets `--vscode-*`, `--text-link-decoration`, VS Code's theme classes,
+and `data-vscode-theme-id`, `data-vscode-theme-name`, and `data-vscode-theme-kind`.
+`data-vscode-theme-id` uses `settingsId` when present, preserving real webview
+selectors; it falls back to `id` for caller-created themes.
+High-contrast light receives both `vscode-high-contrast-light` and
+`vscode-high-contrast`, matching VS Code. Absent properties are masked, rather
+than inheriting a stale value from the previous theme or Explorer.
+
+**Layout and product CSS remain yours.** There is no padding, reset stylesheet,
+link styling or syntax-token palette. A typical fixture surface uses:
+
+```css
+.fixture-root {
+    background: var(--vscode-editor-background);
+    color: var(--vscode-editor-foreground);
+    font-family: var(--vscode-font-family);
+    font-size: var(--vscode-font-size);
+    font-weight: var(--vscode-font-weight);
+}
+```
+
+For an isolated iframe with product selectors such as `body.vscode-dark`, use:
+
+```ts
+import { applyThemeToDocument } from '@vscode/webview-themes';
+
+context.addDisposable(applyThemeToDocument(container.ownerDocument, theme));
+```
+
+This applies variables to that document's root and metadata to its body, just
+like VS Code. Only use it for a document owned by the fixture; it intentionally
+themes the entire document. Use `applyTheme` for siblings or shadow-root content.
+CSS selectors targeting `body` cannot be simulated by a subtree wrapper.
+
+Component Explorer's `background: 'dark' | 'light'` controls its preview canvas,
+not the component's theme. Choose that independently. Inputs can use Explorer's
+`watchInput` to call `setTheme`; the runtime itself does not depend on Explorer
+or Zod, create a picker, or persist a hidden localStorage preference.
+
+## CSS-only use
+
+```ts
+import '@vscode/webview-themes/themes/github-github-vscode-theme-dark-default.css';
+```
+
+```html
+<div class="vscode-theme-github-github-vscode-theme-dark-default vscode-dark">
+    <!-- Component content -->
+</div>
+```
+
+Use the exact `className` from the index rather than reconstructing it. Each CSS
+file contains only one scoped variable rule: no layout, global selectors or
+imports. CSS exports are marked as side effects so bundlers retain them.
+
+For switching, remove the previous named theme class before adding the next one.
+Also update the standard kind classes if product styles use them: `vscode-light`,
+`vscode-dark`, `vscode-high-contrast`, or **both** `vscode-high-contrast-light` and
+`vscode-high-contrast` for high-contrast light. CSS cannot set DOM classes or
+metadata attributes; the JS controller handles those automatically and does not
+need a theme CSS import.
+
+Every generated CSS file resets catalog-known variables absent from its own
+theme to `initial`, preventing inheritance from a different enclosing theme.
+The JSON preserves those variables by omission. Unknown variables from extensions
+not present during extraction are outside the CSS reset set.
+
+## Extract from any VS Code build
+
+```powershell
+vscode-webview-themes --vscode 'C:\path\to\Code.exe' --out-dir .\themes
+```
+
+The executable must be the desktop Electron binary, not the `code` shell
+wrapper. On macOS use the executable inside the application bundle.
+On Linux run under a display, for example:
+
+```sh
+xvfb-run -a vscode-webview-themes --vscode /path/to/code --out-dir ./themes
+```
+
+The CLI supports:
+
+| Option | Meaning |
+| --- | --- |
+| `--vscode <executable>` | Required; caller chooses/downloads/builds VS Code |
+| `--out-dir <directory>` | Generate index, per-theme JSON/CSS and compatibility catalog |
+| `--out <file>` | Legacy aggregate output instead of `--out-dir` |
+| `--extension <directory>` | Repeatable local extension inputs |
+| `--theme <settings-id>` | Repeatable selection; defaults to all available themes |
+| `--timeout <seconds>` | VS Code process deadline; defaults to 300, then up to 5 seconds to stop |
+
+The extractor uses a new temporary user-data directory and extensions directory,
+with automatic theme switching, updates and telemetry disabled. It does not
+connect to your running VS Code, read your profile, or install extensions into
+your normal extensions directory.
+
+Additional extension inputs are copied into this temporary environment. Only
+`contributes.themes` and `contributes.colors` survive in their manifests:
+**their extension code and other contributions are not loaded**. Theme JSONC,
+includes, defaults, and color references are resolved by VS Code itself.
+Supply trusted local theme assets; this is not a sandbox for hostile files.
+
+For a PR-extension fixture, pass the PR extension directory to register its
+`pullRequests.*` colors as well as a GitHub Theme directory to add its themes.
+Neither input directory is modified. Registered color contributions matter:
+a theme's arbitrary color key is not exported by VS Code unless registered.
+
+## Automated catalog refresh
+
+From this project directory:
+
+```sh
+pnpm build
+pnpm update-catalog
+```
+
+The repository-only update script downloads the VS Code version pinned in
+[catalog-sources.json](./catalog-sources.json), downloads/checksums the pinned
+community VSIX packages, and invokes **the same extractor**.
+Use `pnpm update-catalog --vscode <executable>` to supply a different build, or
+`--out <directory>` to emit an artifact without replacing the committed data.
+Adding a community theme requires pinning its version and SHA-256 and reviewing
+its redistribution license; update [ThirdPartyNotices.txt](./ThirdPartyNotices.txt).
+The extractor itself performs no downloads.
+
+**All generated data is checked in under `themes/`.** The updater changes these
+files directly; ordinary `pnpm build` only compiles TypeScript and never downloads
+or refreshes data. JSON, CSS, index and compatibility output are generated from
+one extraction. The index is written last. Removed themes' old JSON/CSS files are
+removed using the previous index; unrelated files are preserved. Validation
+failures occur before writing. Individual file replacements are atomic, but the
+directory is not a transactional snapshot: don't serve it while an update runs.
+
+Both automation hosts can use this:
+
+- **Nightly engineering job:** obtain a VS Code build, run the updater or the
+  standalone CLI, and open a catalog-data PR if the output changed.
+- **VS Code commit CI:** pass the job's packaged executable to the same CLI and
+  upload the generated directory as an artifact. No private workbench API or
+  source patch is needed. An update PR can consume that artifact later.
+
+Scheduling, authentication, release selection, update PRs and npm publication
+are deliberately outside the extractor. The package CI builds/tests and uploads
+an npm tarball; it does not publish or configure a nightly job.
+
+The output records its schema version, VS Code version and build commit,
+platform, architecture, and contributing extension versions. Community archive
+checksums are recorded in the shipped source configuration. Property and theme
+ordering is deterministic; there are no timestamps, user paths or profile IDs.
+The supplied packaged VS Code build must contain `product.json` with a commit.
+Unstamped source-development launches are not accepted as reproducible builds.
+
+Fonts are VS Code's defaults **for the recorded platform**. Refresh on the same
+platform with the same build/extension inputs to obtain byte-identical results.
+Switching the generating OS can legitimately change font variables.
+The JSON snapshots preserve undefined colors by omission; the CSS uses `initial`
+for these tokens, not invented transparent values. TextMate and semantic tokenization, file/product
+icons, product stylesheets, and host messaging are not part of this package.
+
+## Compatibility with the initial prototype
+
+`@vscode/webview-themes/catalog.json`, `parseCatalog`, and `getTheme` remain as
+deprecated compatibility exports for the already-linked PR Explorer. That
+aggregate uses VS Code settings IDs and the old `kind`/`variables` shape.
+`parseTheme` and the controller accept it as input. Parsed themes expose
+non-enumerable, derived `kind` and `variables` accessors for existing callers;
+new code should use `light`, `highContrast`, and `cssVariableValues`.
+The compatibility catalog is generated, never maintained separately.
+
+## Publishing
+
+The existing Azure npm pipelines publish this package using their shared
+`microsoft/vscode-engineering` release template and credentials:
+
+- [Nightly](../.azure-pipelines/publish-nightly.yml): pushes to `main` publish
+  a prerelease under the `next` npm tag. `publishWebviewThemes` defaults to `true`.
+- [Stable](../.azure-pipelines/publish-stable.yml): manually queue the pipeline
+  with `publishWebviewThemes: true` to publish under `latest`. Other package
+  publishing flags can remain disabled.
+
+Both channels use the same [build steps](../.azure-pipelines/webview-themes/build-steps.yml)
+to compile the package and run browser and checked-in asset tests before
+packaging. Releases ship the checked-in snapshots; they do not run extraction
+or update the catalog. Real VS Code extraction remains covered by GitHub Actions.
+
+Use `npm install @vscode/webview-themes@next` after the first successful nightly
+release. The unqualified package name uses `latest` after a stable release.
+Merging the pipeline configuration alone does not confirm publication; verify
+that the Azure publish stage succeeded and the version is available on npm.
+
+## Development and validation
+
+```sh
+pnpm build
+pnpm exec playwright install chromium
+pnpm test
+pnpm test:integration
+pnpm pack
+```
+
+Tests verify every checked-in file matches deterministic generation. Browser
+tests verify real CSS inheritance, standalone CSS switching/nesting, the JS
+controller, cleanup, compatibility and iframe placement.
+Integration tests launch VS Code to check all four theme kinds,
+JSONC/includes, contributed defaults, deterministic output, inactive extension
+code, timeouts and failure preservation. They download the pinned build unless
+`VSCODE_THEMES_EXECUTABLE` names an existing executable. Linux integration tests
+need Xvfb. Both the integration tests and catalog updater create the download
+cache and its parent directories automatically on a fresh checkout.
+Linux CI configures the downloaded `chrome-sandbox` helper with root ownership
+and mode `4755` on the ephemeral runner, keeping Electron sandboxing enabled.
+Integration tests and catalog generation then share that configured executable.
+There are no edits to consumer projects.
+
+### Extraction design
+
+Parsing JSON alone misses derived defaults. Importing `ColorThemeData` can reuse
+the resolver, but collecting all product and extension registrations outside
+the workbench requires maintaining an internal integration. An internal VS Code
+export command could be useful later but would first need a product change.
+
+The probe instead launches VS Code in extension-test mode, selects each theme,
+and captures an otherwise empty webview's injected root properties and body
+metadata. It waits for the exact requested theme ID and validates the response;
+there are no fixed sleeps or light/dark-only change notifications. Mutation
+observers run after VS Code finishes updating the theme metadata and variables.
+The browser receives data only; Electron is an extraction-time requirement.

package/ThirdPartyNotices.txt

@@ -0,0 +1,28 @@
+The bundled catalog includes resolved color values from VS Code's built-in
+themes (Microsoft Corporation, MIT; see LICENSE) and GitHub Theme 6.3.5:
+https://github.com/primer/github-vscode-theme/tree/v6.3.5
+
+GitHub Theme
+-----------
+
+MIT License
+
+Copyright (c) 2020 Primer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/catalog-sources.json

@@ -0,0 +1,11 @@
+{
+    "vscodeVersion": "1.140.0",
+    "extensions": [
+        {
+            "id": "GitHub.github-vscode-theme",
+            "version": "6.3.5",
+            "url": "https://marketplace.visualstudio.com/_apis/public/gallery/publishers/GitHub/vsextensions/github-vscode-theme/6.3.5/vspackage",
+            "sha256": "74e69da1804f718ae9ce6a8ea49c06fbf9cfc137c9b65b0e14353715cb5d474a"
+        }
+    ]
+}

package/dist/extractor/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/extractor/cli.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { extract } from './extract.js';
+try {
+    const { values } = parseArgs({
+        options: {
+            vscode: { type: 'string' },
+            out: { type: 'string' },
+            'out-dir': { type: 'string' },
+            extension: { type: 'string', multiple: true, default: [] },
+            theme: { type: 'string', multiple: true, default: [] },
+            timeout: { type: 'string', default: '300' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    if (values.help) {
+        console.log(`Usage: vscode-webview-themes --vscode <executable> --out-dir <themes-directory>
+  --out-dir <directory>   Write index.json and per-theme JSON/CSS files
+  --out <catalog.json>    Legacy aggregate output (instead of --out-dir)
+  --extension <directory>  Additional theme/color extension (repeatable; code is not loaded)
+  --theme <settings-id>    Only extract these themes (repeatable; default: all)
+  --timeout <seconds>     VS Code process timeout (default: 300)
+
+Uses a fresh isolated profile. No downloads, publication, or changes to your VS Code profile.
+Pass the Electron executable, not the code/code-insiders shell wrapper. On Linux, use xvfb-run.`);
+    }
+    else {
+        const output = values['out-dir'] ?? values.out;
+        if (!values.vscode || !output || (values.out && values['out-dir'])) {
+            throw new Error('--vscode and exactly one of --out-dir or --out are required; see --help');
+        }
+        const timeout = Number(values.timeout);
+        if (!Number.isFinite(timeout) || timeout <= 0) {
+            throw new Error('--timeout must be a positive number of seconds');
+        }
+        await extract({
+            executable: values.vscode,
+            output,
+            format: values['out-dir'] ? 'directory' : 'catalog',
+            extensions: values.extension,
+            themes: values.theme,
+            timeoutMs: timeout * 1000,
+        });
+    }
+}
+catch (error) {
+    console.error(error);
+    process.exitCode = 1;
+}

package/dist/extractor/extract.d.ts

@@ -0,0 +1,9 @@
+export interface ExtractOptions {
+    readonly executable: string;
+    readonly output: string;
+    readonly extensions: readonly string[];
+    readonly themes: readonly string[];
+    readonly timeoutMs: number;
+    readonly format?: 'catalog' | 'directory';
+}
+export declare function extract(options: ExtractOptions): Promise<void>;

package/dist/extractor/extract.js

@@ -0,0 +1,135 @@
+import { spawn } from 'node:child_process';
+import { cp, mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { object, parseCatalog, text } from '../schema.js';
+import { writeThemeFiles } from './themeFiles.js';
+export async function extract(options) {
+    const temporary = await mkdtemp(join(tmpdir(), 'vscode-webview-themes-'));
+    try {
+        const extensionsPath = join(temporary, 'extensions');
+        const userDataPath = join(temporary, 'user-data');
+        const probePath = join(temporary, 'probe');
+        await Promise.all([mkdir(extensionsPath), mkdir(join(userDataPath, 'User'), { recursive: true }), mkdir(probePath)]);
+        const ids = new Set();
+        for (const directory of options.extensions) {
+            const manifest = object(JSON.parse(await readFile(join(directory, 'package.json'), 'utf8')), 'extension manifest');
+            const publisher = text(manifest.publisher, 'publisher');
+            const name = text(manifest.name, 'name');
+            const id = `${publisher}.${name}`;
+            if (!/^[\w-]+\.[\w-]+$/.test(id) || ids.has(id.toLowerCase())) {
+                throw new Error(`Invalid or duplicate extension ID: ${id}`);
+            }
+            ids.add(id.toLowerCase());
+            const contributes = object(manifest.contributes, `${id}.contributes`);
+            if (!Array.isArray(contributes.themes) && !Array.isArray(contributes.colors)) {
+                throw new Error(`${id} has no theme or color contributions`);
+            }
+            const destination = join(extensionsPath, id);
+            await cp(resolve(directory), destination, {
+                recursive: true,
+                filter: source => !['.git', 'node_modules'].includes(basename(source)),
+            });
+            // Never run supplied extensions. Only VS Code's declarative theme/color loaders are needed.
+            await writeFile(join(destination, 'package.json'), JSON.stringify({
+                name, publisher,
+                version: text(manifest.version, `${id}.version`),
+                engines: manifest.engines,
+                contributes: { themes: contributes.themes, colors: contributes.colors },
+            }));
+        }
+        await writeFile(join(probePath, 'package.json'), JSON.stringify({
+            name: 'webview-theme-probe', publisher: 'vscode-theme-extractor', version: '0.0.1',
+            engines: { vscode: '^1.100.0' },
+        }));
+        await writeFile(join(userDataPath, 'User', 'settings.json'), JSON.stringify({
+            'window.autoDetectColorScheme': false,
+            'window.autoDetectHighContrast': false,
+            'workbench.startupEditor': 'none',
+            'workbench.enableExperiments': false,
+            'telemetry.telemetryLevel': 'off',
+            'update.mode': 'none',
+            'extensions.autoUpdate': false,
+            'extensions.autoCheckUpdates': false,
+            'security.workspace.trust.enabled': false,
+        }));
+        const resultPath = join(temporary, 'catalog.json');
+        await launch(options.executable, [
+            '--user-data-dir', userDataPath,
+            '--extensions-dir', extensionsPath,
+            '--extensionDevelopmentPath', probePath,
+            '--extensionTestsPath', fileURLToPath(new URL('./probe.cjs', import.meta.url)),
+            '--skip-welcome', '--skip-release-notes', '--disable-updates', '--disable-telemetry',
+            '--disable-workspace-trust', '--new-window',
+        ], {
+            VSCODE_PORTABLE: temporary,
+            WEBVIEW_THEME_REQUEST: JSON.stringify({ themes: options.themes, extensions: [...ids], output: resultPath }),
+        }, options.timeoutMs);
+        const catalog = parseCatalog(JSON.parse(await readFile(resultPath, 'utf8')));
+        const output = resolve(options.output);
+        if (options.format === 'directory') {
+            await writeThemeFiles(output, catalog);
+            console.log(`Extracted ${catalog.themes.length} JSON/CSS themes from VS Code ${catalog.source.vscodeVersion} to ${output}`);
+            return;
+        }
+        await mkdir(dirname(output), { recursive: true });
+        const staging = `${output}.tmp-${process.pid}`;
+        try {
+            await writeFile(staging, `${JSON.stringify(catalog, null, 2)}\n`);
+            await rename(staging, output);
+        }
+        finally {
+            await rm(staging, { force: true });
+        }
+        console.log(`Extracted ${catalog.themes.length} themes from VS Code ${catalog.source.vscodeVersion} to ${output}`);
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
+    }
+}
+async function launch(executable, args, environment, timeoutMs) {
+    const env = { ...process.env, ...environment };
+    delete env.ELECTRON_RUN_AS_NODE;
+    delete env.VSCODE_IPC_HOOK_CLI;
+    delete env.VSCODE_APPDATA;
+    delete env.VSCODE_EXTENSIONS;
+    delete env.VSCODE_DEV;
+    await new Promise((resolve, reject) => {
+        const child = spawn(executable, args, { env, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+        let failure;
+        let killTimer;
+        const terminate = () => {
+            child.kill();
+            killTimer ??= setTimeout(() => child.kill('SIGKILL'), 5000);
+        };
+        const timer = setTimeout(() => {
+            failure = new Error(`VS Code theme extraction timed out after ${timeoutMs} ms`);
+            terminate();
+        }, timeoutMs);
+        const cancel = () => {
+            failure = new Error('VS Code theme extraction interrupted');
+            terminate();
+        };
+        process.once('SIGINT', cancel);
+        process.once('SIGTERM', cancel);
+        child.stdout.on('data', data => process.stdout.write(data));
+        child.stderr.on('data', data => process.stderr.write(data));
+        const finish = (error) => {
+            clearTimeout(timer);
+            clearTimeout(killTimer);
+            process.removeListener('SIGINT', cancel);
+            process.removeListener('SIGTERM', cancel);
+            child.stdout.destroy();
+            child.stderr.destroy();
+            if (error) {
+                reject(error);
+            }
+            else {
+                resolve();
+            }
+        };
+        child.once('error', error => finish(error));
+        child.once('exit', (code, signal) => finish(failure ?? (code === 0 ? undefined : new Error(`VS Code exited with ${code ?? signal}`))));
+    });
+}