@hydranium/cli 1.0.0-next.40 → 1.0.0-next.401

package/templates/host-browser/src/monaco-editor-worker.ts

@@ -0,0 +1,10 @@
+// Monaco's own editor worker, a third worker hosting no head: Monaco runs link
+// detection, diffs and minimal edits there. `monaco-editor-core` ships no
+// entry for it, so this is one: wait for the first message, then start, which
+// replaces this handler with Monaco's own.
+
+import { start } from 'monaco-editor-core/esm/vs/editor/editor.worker.start.js';
+
+self.onmessage = (): void => {
+   start(() => ({}));
+};

package/templates/host-browser/src/posix-path-shim.ts

@@ -0,0 +1,23 @@
+// The one function of Node's `path` the framework imports, for the bundle to
+// resolve: `esbuild.mjs` points the bare `path` specifier here, while a
+// `node:path` import still fails the bundle. Only a workspace folder given as
+// a filesystem path reaches it, which the page, naming a URI, never does.
+
+/** Resolve `segments` right to left into one absolute path, as `path.posix.resolve` does from `/`. */
+export function resolve(...segments: string[]): string {
+   let resolved = '';
+   for (let i = segments.length - 1; i >= 0 && !resolved.startsWith('/'); i--) {
+      if (segments[i].length > 0) {
+         resolved = resolved.length === 0 ? segments[i] : `${segments[i]}/${resolved}`;
+      }
+   }
+   const parts: string[] = [];
+   for (const part of resolved.split('/')) {
+      if (part === '..') {
+         parts.pop();
+      } else if (part !== '' && part !== '.') {
+         parts.push(part);
+      }
+   }
+   return `/${parts.join('/')}`;
+}

package/templates/host-browser/src/shown-file.ts

@@ -0,0 +1,61 @@
+// The file the page shows: the switch above the panes, between the workspace
+// files the worker holds. Each part follows it, and any part can switch it, so
+// a page with one part fewer still has it.
+
+import type { WorkerHeads } from '@hydranium/client-browser';
+import { WORKSPACE_ROOT_URI } from './workspace.js';
+
+/** The file the page shows, for each part that follows it. */
+export interface ShownFile {
+   /** Each workspace file a language claims, by URI, with the text the worker holds. */
+   readonly files: ReadonlyMap<string, string>;
+   /** The URI of the file shown now. */
+   current(): string;
+   /** Switch the page to `uri`, one of {@link files}. */
+   show(uri: string): void;
+   /** Call `listener` with the URI of each file the page switches to. */
+   onDidChange(listener: (uri: string) => void): void;
+}
+
+/**
+ * Fill the switch with the files of `languages` the worker sent once its heads
+ * were up, and show the first.
+ */
+export async function startShownFile(
+   heads: WorkerHeads,
+   languages: ReadonlyArray<{ readonly fileExtensions: readonly string[] }>
+): Promise<ShownFile> {
+   // The text comes from the worker rather than the seed, since a saved edit
+   // is laid over the seed there.
+   const { workspace } = await heads.ready;
+   if (workspace === undefined) {
+      throw new Error('the worker sent no workspace files');
+   }
+   // Only the files a part of the page can show: one of another language would show nothing.
+   const claimed = (path: string): boolean =>
+      languages.some(language => language.fileExtensions.some(extension => path.endsWith(extension)));
+   const paths = Object.keys(workspace.files).filter(claimed).sort();
+   if (paths.length === 0) {
+      throw new Error('no workspace file has an extension the page shows');
+   }
+   const files = new Map(paths.map(path => [`${WORKSPACE_ROOT_URI}/${path}`, workspace.files[path]]));
+
+   const select = document.getElementById('file') as HTMLSelectElement;
+   // The worker keys each file by its encoded path, as in its URI: shown decoded.
+   select.append(...paths.map(path => new Option(decodeURIComponent(path), `${WORKSPACE_ROOT_URI}/${path}`)));
+   let shown = select.value;
+   const listeners: Array<(uri: string) => void> = [];
+   const show = (uri: string): void => {
+      if (!files.has(uri)) {
+         throw new Error(`${uri} is not a workspace file the page shows`);
+      }
+      select.value = uri;
+      if (uri !== shown) {
+         shown = uri;
+         listeners.forEach(listener => listener(uri));
+      }
+   };
+   select.addEventListener('change', () => show(select.value));
+   select.hidden = false;
+   return { files, current: () => shown, show, onDidChange: listener => listeners.push(listener) };
+}

package/templates/host-browser/src/workspace.ts

@@ -0,0 +1,5 @@
+// The workspace root both ends name: the worker seeds its filesystem under it
+// and the page opens documents by URIs below it.
+
+/** The URI of the workspace root, which holds the files of `../workspace`. */
+export const WORKSPACE_ROOT_URI = 'file:///workspace';

package/templates/host-browser/tsconfig.e2e.json

@@ -0,0 +1,16 @@
+// The smoke tier's half, which runs in Node under Playwright. `test:e2e` passes
+// it with `--tsconfig`, since Playwright otherwise looks for a `tsconfig.json`
+// in the directories above.
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["test", "playwright.config.mts"]
+}

package/templates/host-browser/tsconfig.page.json

@@ -0,0 +1,16 @@
+// The page's half, everything in `src` but the worker, with the DOM library.
+// esbuild emits, so this only type-checks.
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": []
+  },
+  "include": ["src"],
+  "exclude": ["src/worker.ts"]
+}

package/templates/host-browser/tsconfig.worker.json

@@ -0,0 +1,16 @@
+// The worker's half: the heads run in a worker, which has no DOM, and the
+// worker and DOM libraries declare conflicting globals, so the page is a
+// project of its own. esbuild emits, so this only type-checks.
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "WebWorker"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": []
+  },
+  "files": ["src/worker.ts"]
+}

package/templates/host-theia-browser/esbuild.mjs

@@ -0,0 +1,24 @@
+/**
+ * This file can be edited to adjust the ESBuild build process.
+ * To reset, delete this file and rerun theia build again.
+ */
+import { browserOptions, watch } from './gen-esbuild.browser.mjs';
+import { nodeOptions } from './gen-esbuild.node.mjs';
+
+import esbuild from 'esbuild';
+
+const browserContext = await esbuild.context(browserOptions);
+const nodeContext = await esbuild.context(nodeOptions);
+
+if (watch) {
+   await Promise.all([browserContext.watch(), nodeContext.watch()]);
+} else {
+   try {
+      await browserContext.rebuild();
+      await browserContext.dispose();
+      await nodeContext.rebuild();
+      await nodeContext.dispose();
+   } catch {
+      process.exit(1);
+   }
+}

package/templates/host-theia-browser/gitignore

@@ -0,0 +1,9 @@
+node_modules/
+# What `theia build` generates.
+lib/
+src-gen/
+gen-esbuild.*.mjs
+plugins/
+smoke-workspace/
+test-results/
+playwright-report/

package/templates/host-theia-browser/playwright.config.mts

@@ -0,0 +1,42 @@
+// The smoke tier: Playwright starts the application on a copy of the starter
+// workspace, since the server writes its repairs to the folder it opens, and
+// drives it in Chromium, which `npm run test:e2e:install` downloads once.
+// `npm start` serves what `npm run build` bundled, so build first.
+
+import { defineConfig, devices } from '@playwright/test';
+import { cpSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * The port the smoke serves on, not `npm start`'s 3000, so a running
+ * application doesn't block it; set `THEIA_PORT` to choose another.
+ */
+const PORT = Number(process.env.THEIA_PORT || 4938);
+
+// Copied once, by the runner: its workers load this file again, and inherit the flag.
+if (process.env.SMOKE_WORKSPACE_COPIED === undefined) {
+   process.env.SMOKE_WORKSPACE_COPIED = 'true';
+   const workspace = new URL('smoke-workspace', import.meta.url);
+   rmSync(workspace, { recursive: true, force: true });
+   cpSync(new URL('../workspace', import.meta.url), workspace, { recursive: true });
+   // Settings of its own too, so a run never writes `~/.theia/settings.json`.
+   process.env.THEIA_CONFIG_DIR ??= mkdtempSync(join(tmpdir(), 'theia-smoke-config-'));
+}
+
+export default defineConfig({
+   testDir: './test',
+   // The first request waits for the backend to start the server and build the workspace.
+   timeout: 120_000,
+   expect: { timeout: 60_000 },
+   use: { ...devices['Desktop Chrome'], baseURL: `http://localhost:${PORT}` },
+   webServer: {
+      // Relative to this folder, the server's working directory.
+      command: 'node start.mjs smoke-workspace',
+      url: `http://localhost:${PORT}`,
+      env: { THEIA_PORT: String(PORT) },
+      // A server already on the port fails the run rather than being tested in this one's place.
+      reuseExistingServer: false,
+      timeout: 120_000
+   }
+});

package/templates/host-theia-browser/start.mjs

@@ -0,0 +1,50 @@
+// `npm start`: the Theia backend on `THEIA_PORT`, 3000 when it is unset, on the
+// folder given as the argument, `../workspace` when there is none. A script
+// rather than `--port=${THEIA_PORT:-3000}` in package.json: only a POSIX shell
+// expands that, and npm also runs scripts under cmd.exe.
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Paths from this file, not the working directory, which a direct `node` run can set anywhere.
+const here = path.dirname(fileURLToPath(import.meta.url));
+const link = path.join(here, 'plugins', '__PROJECT_ID__-vscode-servers');
+
+// The servers extension, sideloaded from plugins/ beside any other plugin there.
+// Linked here rather than in the build, which a build cache can replay without
+// it; replaced every time, since a dangling link left by a moved extension
+// fails `symlinkSync`.
+fs.mkdirSync(path.dirname(link), { recursive: true });
+const existing = fs.lstatSync(link, { throwIfNoEntry: false });
+// A link, a junction included, is unlinked, never handed to a recursive remove
+// that might reach `../vscode-servers` through it.
+if (existing?.isSymbolicLink()) {
+   fs.unlinkSync(link);
+} else {
+   fs.rmSync(link, { recursive: true, force: true });
+}
+fs.symlinkSync(path.join(here, '../vscode-servers'), link, 'junction');
+
+const port = Number(process.env.THEIA_PORT || 3000);
+const workspace = path.resolve(process.argv[2] ?? path.join(here, '../workspace'));
+// The CLI run by this Node, with no shell: the workspace path reaches Theia as it is.
+// `local-dir:` relative to `cwd`, since Theia reads an absolute path as a URI.
+const cli = createRequire(import.meta.url).resolve('@theia/cli/bin/theia.js');
+const theia = spawn(process.execPath, [cli, 'start', '--plugins=local-dir:./plugins', `--port=${port}`, workspace], {
+   cwd: here,
+   stdio: 'inherit'
+});
+for (const signal of ['SIGINT', 'SIGTERM']) {
+   process.on(signal, () => theia.kill(signal));
+}
+theia.on('exit', (code, signal) => {
+   if (signal === null) {
+      process.exit(code ?? 1);
+   }
+   // Ended by a signal, so end by it too: Ctrl+C is a stop, not a failure.
+   process.removeAllListeners(signal);
+   process.kill(process.pid, signal);
+});

package/templates/host-theia-browser/tsconfig.e2e.json

@@ -0,0 +1,16 @@
+// The smoke tier, which runs in Node under Playwright. `test:e2e` passes it
+// with `--tsconfig`, since Playwright otherwise looks for a `tsconfig.json` in
+// the directories above.
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["test", "playwright.config.mts"]
+}

package/templates/host-theia-electron/esbuild.mjs

@@ -0,0 +1,27 @@
+/**
+ * This file can be edited to adjust the ESBuild build process.
+ * To reset, delete this file and rerun theia build again.
+ */
+import { browserOptions, watch } from './gen-esbuild.browser.mjs';
+import { nodeOptions } from './gen-esbuild.node.mjs';
+import { electronOptions } from './gen-esbuild.electron.mjs';
+import esbuild from 'esbuild';
+
+const browserContext = await esbuild.context(browserOptions);
+const nodeContext = await esbuild.context(nodeOptions);
+const electronContext = await esbuild.context(electronOptions);
+
+if (watch) {
+   await Promise.all([browserContext.watch(), nodeContext.watch(), electronContext.watch()]);
+} else {
+   try {
+      await browserContext.rebuild();
+      await browserContext.dispose();
+      await nodeContext.rebuild();
+      await nodeContext.dispose();
+      await electronContext.rebuild();
+      await electronContext.dispose();
+   } catch {
+      process.exit(1);
+   }
+}

package/templates/host-theia-electron/gitignore

@@ -0,0 +1,8 @@
+node_modules/
+# What `theia build` generates.
+lib/
+src-gen/
+gen-esbuild.*.mjs
+plugins/
+test-results/
+playwright-report/

package/templates/host-theia-electron/playwright.config.mts

@@ -0,0 +1,12 @@
+// The smoke tier: the test launches the application in Electron itself, so
+// there is no server to start here. It runs what `npm run build` bundled, so
+// build first.
+
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+   testDir: './test',
+   // The first window waits for the backend to start the server and build the workspace.
+   timeout: 120_000,
+   expect: { timeout: 60_000 }
+});

package/templates/host-theia-electron/start.mjs

@@ -0,0 +1,47 @@
+// `npm start`: the Theia desktop application on the folder given as the
+// argument, `../workspace` when there is none.
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Paths from this file, not the working directory, which a direct `node` run can set anywhere.
+const here = path.dirname(fileURLToPath(import.meta.url));
+const link = path.join(here, 'plugins', '__PROJECT_ID__-vscode-servers');
+
+// The servers extension, sideloaded from plugins/ beside any other plugin there.
+// Linked here rather than in the build, which a build cache can replay without
+// it; replaced every time, since a dangling link left by a moved extension
+// fails `symlinkSync`.
+fs.mkdirSync(path.dirname(link), { recursive: true });
+const existing = fs.lstatSync(link, { throwIfNoEntry: false });
+// A link, a junction included, is unlinked, never handed to a recursive remove
+// that might reach `../vscode-servers` through it.
+if (existing?.isSymbolicLink()) {
+   fs.unlinkSync(link);
+} else {
+   fs.rmSync(link, { recursive: true, force: true });
+}
+fs.symlinkSync(path.join(here, '../vscode-servers'), link, 'junction');
+
+const workspace = path.resolve(process.argv[2] ?? path.join(here, '../workspace'));
+// The CLI run by this Node, with no shell: the workspace path reaches Theia as it is.
+// `local-dir:` relative to `cwd`, since Theia reads an absolute path as a URI.
+const cli = createRequire(import.meta.url).resolve('@theia/cli/bin/theia.js');
+const theia = spawn(process.execPath, [cli, 'start', '--plugins=local-dir:./plugins', workspace], {
+   cwd: here,
+   stdio: 'inherit'
+});
+for (const signal of ['SIGINT', 'SIGTERM']) {
+   process.on(signal, () => theia.kill(signal));
+}
+theia.on('exit', (code, signal) => {
+   if (signal === null) {
+      process.exit(code ?? 1);
+   }
+   // Ended by a signal, so end by it too: Ctrl+C is a stop, not a failure.
+   process.removeAllListeners(signal);
+   process.kill(process.pid, signal);
+});

package/templates/host-theia-electron/tsconfig.e2e.json

@@ -0,0 +1,16 @@
+// The smoke tier, which runs in Node under Playwright. `test:e2e` passes it
+// with `--tsconfig`, since Playwright otherwise looks for a `tsconfig.json` in
+// the directories above.
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["test", "playwright.config.mts"]
+}

package/templates/host-vscode/esbuild.mjs

@@ -0,0 +1,38 @@
+// Bundles each diagram webview in `src/webview/` into `out/webview/`, its
+// stylesheet beside it: once, or on every change with `--watch`. The extension
+// itself is `tsc`'s, since the extension host loads it with its `node_modules`.
+//
+// At `platform: 'browser'` esbuild refuses a `node:*` import rather than
+// shimming it, so a Node import reaching a webview fails here rather than in
+// the webview's own console.
+
+import { context } from 'esbuild';
+import { readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const root = fileURLToPath(new URL('.', import.meta.url));
+
+const build = await context({
+   absWorkingDir: root,
+   entryPoints: readdirSync(new URL('src/webview/', import.meta.url))
+      .filter(file => file.endsWith('.ts'))
+      .map(file => `src/webview/${file}`),
+   outdir: 'out/webview',
+   bundle: true,
+   platform: 'browser',
+   // The editor loads the bundle with a plain `<script>`.
+   format: 'iife',
+   target: 'es2022',
+   sourcemap: true,
+   // The icon font GLSP imports, inlined: a webview loads only the URIs the
+   // extension mints at runtime, which a bundled `url()` cannot name.
+   loader: { '.ttf': 'dataurl' },
+   logLevel: 'info'
+});
+
+if (process.argv.includes('--watch')) {
+   await build.watch();
+} else {
+   await build.rebuild();
+   await build.dispose();
+}

package/templates/host-vscode/gitignore

@@ -0,0 +1,7 @@
+node_modules/
+out/
+syntaxes/
+*.tsbuildinfo
+.vscode-test/
+test-results/
+playwright-report/

package/templates/host-vscode/playwright.config.mts

@@ -0,0 +1,14 @@
+// The smoke tier: each test launches the VS Code `npm run test:e2e:install`
+// downloaded, with this extension loaded from `out/`, so build first. On Linux
+// without a display, run it under `xvfb-run -a`.
+
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+   testDir: './test',
+   // The first request waits for the server to build the workspace.
+   timeout: 120_000,
+   expect: { timeout: 60_000 },
+   // One VS Code at a time.
+   workers: 1
+});

package/templates/host-vscode/src/__GRAMMAR_ID__-diagram-editor.ts

@@ -0,0 +1,19 @@
+// The __GRAMMAR__ diagram's custom editor: a webview over the diagram bundle
+// esbuild writes to `out/webview/`.
+
+import { HydraniumGlspEditorProvider } from '@hydranium/glsp-client-vscode/node';
+import { __GRAMMAR_ID_CONST___DIAGRAM_TYPE } from '__PROTOCOL_PACKAGE__';
+
+/**
+ * The view type `contributes.customEditors` in `package.json` declares. VS Code
+ * reads the manifest statically, so the two are kept equal by hand, and a
+ * mismatch leaves the file with no diagram editor.
+ */
+export const __GRAMMAR_ID_CONST___DIAGRAM_VIEW_TYPE = '__LANGUAGE_ID__.diagram';
+
+export class __GRAMMAR__DiagramEditorProvider extends HydraniumGlspEditorProvider {
+   override diagramType = __GRAMMAR_ID_CONST___DIAGRAM_TYPE;
+   protected override readonly scriptPath = 'out/webview/__GRAMMAR_ID__-diagram.js';
+   protected override readonly stylePath = 'out/webview/__GRAMMAR_ID__-diagram.css';
+   protected override readonly title = '__GRAMMAR__ Diagram';
+}

package/templates/host-vscode/src/show-model-command.ts

@@ -0,0 +1,24 @@
+// `__NAME__: Show Model`: the active tab's file, text or diagram, read through
+// the data head, and its root type shown in a notification.
+
+import type { DataConnectionWithEvents } from '@hydranium/protocol';
+import { ALL_LANGUAGES, type __NAME__Element } from '__PROTOCOL_PACKAGE__';
+import { TabInputCustom, TabInputText, window } from 'vscode';
+
+/** The command's handler, reading through `connection`. */
+export function showModelCommand(connection: DataConnectionWithEvents<__NAME__Element>): () => Promise<void> {
+   // Opened on the first run and kept until the connection is disposed.
+   let session: ReturnType<typeof connection.createSession> | undefined;
+   return async () => {
+      const input = window.tabGroups.activeTabGroup.activeTab?.input;
+      const uri = input instanceof TabInputText || input instanceof TabInputCustom ? input.uri : undefined;
+      if (uri === undefined || !ALL_LANGUAGES.some(language => language.fileExtensions.some(extension => uri.path.endsWith(extension)))) {
+         void window.showInformationMessage('Open a __NAME__ file first.');
+         return;
+      }
+      session ??= connection.createSession('__PROJECT_ID__-show-model');
+      const root = await session.withOpenDocument({ uri: uri.toString() }, document => document.model?.root.$type);
+      const file = uri.path.slice(uri.path.lastIndexOf('/') + 1);
+      void window.showInformationMessage(`${file} holds a ${root ?? 'document with no model'}`);
+   };
+}

package/templates/host-vscode/src/webview/__GRAMMAR_ID__-diagram.ts

@@ -0,0 +1,18 @@
+// The __GRAMMAR__ diagram webview: GLSP's handshake with the extension host,
+// over the diagram the client package defines. Never import this from the
+// extension: its graph reaches stylesheets, which Node cannot load.
+
+import type { ContainerConfiguration } from '@eclipse-glsp/client';
+import { HydraniumGlspStarter } from '@hydranium/glsp-client-vscode/browser';
+import { Container } from 'inversify';
+import { initialize__GRAMMAR__DiagramContainer } from '__CLIENT_PACKAGE__';
+// Last, so its rules follow GLSP's stylesheet in the bundle.
+import './diagram.css';
+
+class __GRAMMAR__DiagramStarter extends HydraniumGlspStarter {
+   createContainer(...containerConfiguration: ContainerConfiguration): Container {
+      return initialize__GRAMMAR__DiagramContainer(new Container(), ...containerConfiguration);
+   }
+}
+
+new __GRAMMAR__DiagramStarter();

package/templates/host-vscode/src/webview/diagram.css

@@ -0,0 +1,40 @@
+/* The diagram webviews' size and colours, bundled after GLSP's stylesheet so
+   these rules win on equal specificity. */
+
+/* A webview has no layout above the document, so each element down to the
+   SVG needs a height, or the diagram draws at zero height. */
+html,
+body {
+   height: 100%;
+   width: 100%;
+   margin: 0;
+   padding: 0;
+   overflow: hidden;
+}
+
+.hydranium-diagram-container,
+.hydranium-diagram-container > .sprotty,
+.hydranium-diagram-container > .sprotty > svg {
+   height: 100%;
+   width: 100%;
+   display: block;
+}
+
+/* The editor's theme, rather than GLSP's colours for a light canvas. */
+.sprotty {
+   background: var(--vscode-editor-background);
+   color: var(--vscode-editor-foreground);
+   font-family: var(--vscode-font-family);
+   font-size: var(--vscode-font-size);
+}
+
+/* GLSP's stylesheet leaves shapes at the SVG defaults: a black fill, and no stroke on an edge. */
+.sprotty-node {
+   fill: var(--vscode-editorWidget-background);
+   stroke: var(--vscode-focusBorder);
+}
+
+.sprotty-edge {
+   fill: none;
+   stroke: var(--vscode-editor-foreground);
+}

package/templates/host-vscode/start.mjs

@@ -0,0 +1,22 @@
+// Starts VS Code with this extension on `../workspace`. VS Code reads a
+// relative `--extensionDevelopmentPath` against its own working directory
+// rather than this one, so both paths are made absolute here.
+
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const args = [
+   `--extensionDevelopmentPath=${fileURLToPath(new URL('.', import.meta.url))}`,
+   fileURLToPath(new URL('../workspace', import.meta.url))
+];
+// On Windows `code` is a `.cmd`, which only a shell runs. The shell gets one
+// command line, as Node deprecates arguments beside `shell: true`, and each
+// path is quoted so the shell does not split one with a space.
+const child =
+   process.platform === 'win32'
+      ? spawn(['code', ...args.map(arg => `"${arg}"`)].join(' '), { stdio: 'inherit', shell: true })
+      : spawn('code', args, { stdio: 'inherit' });
+child.on('error', error => {
+   console.error(`Could not start VS Code: ${error.message}. npm start needs \`code\` on the PATH.`);
+   process.exitCode = 1;
+});

package/templates/host-vscode/test/install-vscode.mts

@@ -0,0 +1,21 @@
+// Downloads the pinned VS Code into `.vscode-test/`, retrying, so the smoke
+// test finds it there and asks the update server nothing.
+
+import { downloadAndUnzipVSCode } from '@vscode/test-electron';
+import { setTimeout } from 'node:timers/promises';
+import { VSCODE_CACHE, VSCODE_VERSION } from './vscode-version.mts';
+
+const ATTEMPTS = 3;
+
+for (let attempt = 1; ; attempt++) {
+   try {
+      await downloadAndUnzipVSCode({ version: VSCODE_VERSION, cachePath: VSCODE_CACHE });
+      break;
+   } catch (error: unknown) {
+      if (attempt === ATTEMPTS) {
+         throw error;
+      }
+      console.warn(`Downloading VS Code ${VSCODE_VERSION} failed, attempt ${attempt} of ${ATTEMPTS}.`, error);
+      await setTimeout(attempt * 5_000);
+   }
+}

package/templates/host-vscode/test/vscode-version.mts

@@ -0,0 +1,10 @@
+import { fileURLToPath } from 'node:url';
+
+/**
+ * The VS Code build the smoke test downloads and runs. Pinned rather than
+ * `stable`, so a VS Code release cannot fail a run with no change here.
+ */
+export const VSCODE_VERSION = '1.141.0';
+
+/** Where `@vscode/test-electron` keeps the download, below this package. */
+export const VSCODE_CACHE = fileURLToPath(new URL('../.vscode-test', import.meta.url));