Playground TS plugin bootstrap can fail silently on read-only extension installs

[tnaum-ms]

Problem statement

To make the Query Playground TS server plugin discoverable, the extension creates a stub at runtime inside its own install directory:

<extension>/node_modules/documentdb-playground-ts-plugin/index.js

This is implemented in src/documentdb/ClustersExtension.ts inside ensureTsRestart. The stub is a workaround because @vscode/vsce hardcodes ignore: 'node_modules/**' and the plugin cannot ship inside the VSIX. The long-term fix is tracked in #548 (publish the plugin as a standalone npm package).

The runtime stub install assumes that the extension install directory is writable, which is not always the case:

• VS Code installed via Snap or a system package manager (for example /usr/share/code/... on Linux).
• VS Code Server inside hardened containers or air-gapped enterprise deployments.
• Codespaces or dev container images where the extensions layer is read only.
• Roaming or managed installs where the extension files live on a network share.

In these environments fs.mkdirSync / fs.writeFileSync throw EACCES or EROFS. The current implementation now reports the failure through telemetry (playground.tsPluginBootstrap event with stage, stubCreated, error name and message) and resets the retry flag so a subsequent playground open will try again. That gives us observability and best effort recovery, but the underlying root cause remains: we cannot rely on writing into the extension install directory.

Why this matters

Playground IntelliSense (method completions, parameter help, signatures backed by the TS server plugin) becomes unavailable. Other custom completions (collection names, operators, BSON constructors) keep working because they are provided by the in-process CompletionItemProvider. So the failure mode is "everything still works, but TypeScript-aware completions are quietly missing", which is hard for users to self-diagnose.

Suggested solutions

In rough order of preference.

1. Publish the plugin as a real npm dependency (preferred long term). Tracked in WIP: Publish TS server plugin as standalone npm package #548. Removes the stub entirely and follows the official typescriptServerPlugins contract.
2. Write the stub into the extension's global storage path (ext.context.globalStorageUri.fsPath) and have the plugin loader resolve from there. Global storage is always writable. Trade off: the TS server resolves plugins relative to the extension root, so we may need to publish a thin shim package whose only job is to redirect to the global-storage location.
3. Ship the stub via the build pipeline instead of at runtime. Investigate whether vsce package --no-dependencies plus a custom files glob allows a single node_modules/<plugin>/index.js shim to be included. Recent vsce versions accept --packagePath and --baseImagesUrl, but the node_modules/** ignore is still hardcoded; verify against the current version.
4. Detect read-only state up front and surface a status bar hint when the bootstrap fails, with a link to a documentation page that explains the limitation and offers a workaround (for example installing VS Code from the standalone tarball instead of Snap).
5. Fall back to a degraded but functional experience: even without the TS plugin, surface a one-time notification telling the user that method completions are unavailable for this install, with a "Don't show again" toggle.

References

• Code: src/documentdb/ClustersExtension.ts (ensureTsRestart).
• Telemetry event added in PR for 0.8.1: playground.tsPluginBootstrap with properties stage, stubCreated, tsExtensionFound.
• Related: WIP: Publish TS server plugin as standalone npm package #548 (publish TS plugin as standalone npm package).
• Design rationale: docs/ai-and-plans/interactive-shell/7-playground-completion-provider.md.
• VS Code docs: contributes.typescriptServerPlugins.
• Pattern reference: vuejs/language-tools uses the same runtime stub workaround.

Definition of done

• Telemetry from 0.8.1+ shows a clear measurement of how often the bootstrap fails and at which stage.
• A decision is recorded for which long-term approach to take (1, 2, or 3 above).
• The runtime stub mutation under extension.../node_modules/ is removed or made resilient on read-only installs.