Bundle the ggsql-jupyter kernel into the VS Code extension

[samclark2015]

Installing the ggsql extension is now enough to run queries in Positron — no separate native installer. Groundwork for posit-dev/positron#14954.

Today the extension registers a runtime for a kernel that may not exist, and starting a session fails with KS-19: Kernel path not found: ggsql-jupyter.

What changes

Extension (ggsql-vscode/src/manager.ts, package.json)

• Discovers a kernel at <extensionPath>/bundled/bin/ggsql-jupyter[.exe], which the per-platform VSIXes now carry.
• Every kernel found is offered, and the user picks in the New Console Session picker. There is one order, not a set of strategies: ggsql.kernelPath, then the bundled kernel, then Jupyter kernelspecs, native install locations, and PATH. Order decides which the picker lists first — hence the default — and which occurrence survives deduplication when two paths name one file. The bundled kernel leads unless the user named one, so a machine with nothing installed gets a working runtime and a machine with an install keeps being offered it.
• Fixes the phantom runtime. Discovery appended the bare binary name whether or not it was on PATH, and the accessibility check waved through any non-absolute path. With no kernel and no bundle, discovery now yields zero runtimes instead of one that fails at session start.
• A kernel is run before it is offered, and what it says is what the picker shows. probeKernel() runs ggsql-jupyter --version (a flag the kernel gains in this PR; there was no way to ask before) and names the runtime ggsql 0.4.1, the way Positron's own runtimes are. Filesystem checks cannot tell whether a binary starts: on Linux a bundled kernel rejected by the dynamic linker is the common case, not an edge one — the kernels are built on Ubuntu 24.04 and need GLIBC_2.39, while Positron supports back to Ubuntu 20.04 and RHEL 9.
• Kernels older than the flag are still offered. They reject --version and exit non-zero, which by exit status alone is the same answer the loader-killed binary gives. The probe separates them by asking a question every version answers — --help — and only a kernel that fails that counts as unable to run; one that passes is offered as plain ggsql (<source>) with no version. Dropping them would take away the install the user already had. Beyond that, only the bundled kernel has to pass at all: a kernel the user installed is their own business.
• A probe success is cached in globalState, keyed by kernel path with the file's mtime and size in the entry, so an install upgraded in place is probed again rather than reporting the version it used to have, and a pass costs one spawn per kernel per install rather than one per window. A failure is not cached, so a host that gains the missing libraries starts working without waiting for an update.
• The Jupyter kernel spec is written only for the leading kernel that passed — it outlives the window, is what Quarto resolves, and has no fallback. Only the dead end — nothing runnable anywhere, whether the bundled kernel failed or the build carries none — raises one non-modal notice per extension version; a kernel merely skipped is reported in the log.
• The bundled kernel gets a fixed runtimeId rather than one hashed from its path: that path contains the versioned extension directory, so hashing it would mint a new runtime on every update and lose runtime affinity and the session restore added in 56174ec. validateMetadata() is what makes that safe — it regenerates the metadata Positron stored for the workspace, so the id survives an update while the stale path in the stored copy does not, and it rejects metadata with no matching candidate, which is how Positron learns to drop a runtime whose kernel has been uninstalled. The bundled runtime also shows as plain ggsql, since it is the default and has nothing to distinguish itself from.

Release (.github/workflows/release-packages.yml)

• Each platform job uploads its ggsql-jupyter as an artifact, taken after signing so the extension ships the same binary the installer does.
• build-vsix stages that artifact and packages six VSIXes: five platform targets plus a kernel-less universal build for everything else. publish-openvsx publishes them.
• This has to live in release-packages.yml: Actions artifacts are run-scoped, and two workflows triggered by the same tag run in parallel, so a separate workflow could not reach the kernels. release-vscode.yaml is retired.
• create-release's globs are now scoped per artifact directory. artifacts/**/*.exe would also have matched the raw ggsql-jupyter.exe, publishing one platform's bare kernel next to the installers.

Tests — src/test/kernelDiscovery.test.ts is 44 tests, plus a 3-test Positron integration suite

• A Positron integration suite (src/test/integration/) that launches the bundled kernel via @posit-dev/positron-test-electron: asserts one registered ggsql runtime with the ggsql-bundled id under bundled/bin/, its name matching ggsql <version> — the only check that the version really comes back from the binary — and that executeCode starts a session and returns a result. Everything else about bundling can pass while the binary fails to start; only this catches that.
• discoverAllRuntimes had no coverage, so "no kernel means no runtime" was only asserted at selectKernelCandidates, which returns candidates rather than runtimes. Testing it needed a seam: discovery writes a Jupyter kernel spec as a side effect, and with the default directory a test run would repoint the real kernelspec at a fixture, so GgsqlRuntimeManager takes an optional kernelSpecDir.
• The probe needed a seam too: a fixture file cannot be a runnable kernel, so the manager takes an optional probe (and a globalState stand-in for the cache), and the registration tests inject the verdict — every install being offered, the once-per-version warning, the cache surviving a new window, metadata revalidation. A separate kernel probe suite exercises the real probeKernel against actual binaries: exit zero, exit zero without a version, a kernel that predates --version, one that rejects every argument, not executable, missing.
• Host discovery and the symlink dedupe are covered by redirecting HOME/PATH instead of depending on what the developer has installed. That isolation now also covers the tests that assert on every runtime without staging a host kernel: running the extension writes the user kernelspec, so a session in the Extension Development Host left a kernel behind that the suite then discovered, and two tests failed on any machine the extension had been used on.
• test-extension.yaml gains a three-OS matrix — discovery branches on the OS for the binary name, the PATH lookup, the executable-bit repair and the locations it searches — and a packaging check on every PR rather than only at release time, run after the tests so that .vscode-test/ is populated and an ignore rule letting a cache into the package actually fails. The integration job adds no cache of its own: it restores publish.yaml's with save-if: false. That workflow runs on every PR and builds this same binary on the same toolchain and lockfile, so the key is an exact match and the kernel build comes back warm (~16 min cold, under 3 warm) without spending a byte against a 10 GB repo limit other workflows have already mostly used.

Packaging (ggsql-vscode/.vscodeignore)

• Removes the !**/*.d.ts re-inclusion. Both test caches are excluded, but that later rule pulled 269 stray .d.ts files back out of them and into the VSIX, because the last matching rule wins. Pre-existing on main (134 of them from .vscode-test/); nothing reads a .d.ts at runtime. The universal build drops from 149 files to 15.
• Excludes .positron-test/, or vsce package walks the 2.9 GB Positron download and dies in its secret scanner on a directory symlink inside the app bundle.

Verified, not assumed

• Open VSX takes the platform from the TargetPlatform attribute vsce package --target writes into extension.vsixmanifest, defaulting to universal when absent (ExtensionProcessor.getTargetPlatform()), and ovsx discards a target option for an already-packaged vsix. So the packaged file is published as-is, with no target passed to the publish action.
• Packaged locally with a real kernel: 46.3 MiB binary, 16.21 MiB VSIX over 16 files (the plan projected ~15.6 MiB), and 106 KB for the kernel-less universal build.
• extension/bundled/bin/ggsql-jupyter ships without adding a .vscodeignore rule, the zip preserves -rwxr-xr-x, and the universal build has neither the attribute nor the binary. build-vsix asserts all of this per target so a targeted-but-empty VSIX cannot be published.
• The probe's handling of an older kernel was checked against two real pre---version installs in an Extension Development Host, which are now offered as ggsql (Jupyter) and ggsql (Path) alongside the bundled ggsql 0.4.1.

Testing

CI covers the extension code on three platforms plus the kernel launch. Nothing on a PR exercises release-packages.yml, so it needs one manual dry run before merge — publishing is gated on refs/tags/v*, so a branch dispatch builds all five kernels and all six VSIXes and publishes nothing:

gh workflow run "Release Cargo and Installer Packages" --ref sclark/bundle-kernel-in-vsix

Not in this PR

• win32-arm64 is not built (no runner produces that kernel). The universal VSIX is not a fallback: Positron's bootstrap appends ?targetPlatform=<target> and gets HTTP 403 for a target that was never published. The Positron-side entry needs either this target or a universal fallback in build/lib/extensions.ts.
• Docs: ggsql-vscode/README.md, doc/get_started/tooling.qmd, and the stale dylibbundler note in INSTALLERS.md.
• The VSIX version comes from ggsql-vscode/package.json, not the tag. Tagging v0.5.0 without bumping it would republish 0.4.1 and, with skipDuplicate, silently skip all six publishes.

🤖 Generated with Claude Code

[georgestagg]

Thanks, this looks good overall! Just a few things before we merge:

1. I pushed a commit to reduce Claude's trademark over-commenting and prose.

1a. I also pushed a commit to fix a latent CI issue.

3. With this, we now inspect --version with every kernel. It would be good if the returned version was interpolated into the title c.f. R/Python kernels in this screenshot:

...

4. Previously, if you had multiple versions of ggsql installed (e.g. System install, one on path, installed via kernelspec), they would all be shown in the New Console Session picker. With this, by default only the bundled version is shown in the picker.

I think we should find all versions available and show all of them. I am happy for the bundled "ggsql" entry to be implied to be the default by omitting "(Bundled)" or similar, but if we find others we should still offer them by default and add "(System)" etc. to disambiguate.

5. Related to 3, if I set the "ggsql.kernelStrategy": "environment", it is closer to what I'd like. As such, do we really need this setting at all? If we just search everywhere, including the user's ggsql.kernelPath, and agree to show everything to the user, then we can remove this setting, right? As above, I think I'd prefer that.

---

Finally, here are some LLM review items. Most weren't important but here are two that might be worth looking into:

• important (correctness) — ggsql-vscode/src/manager.ts:502, ggsql-vscode/src/manager.ts:524: the fixed ggsql-bundled runtime ID deliberately survives extension updates, but its runtimePath still points inside the versioned extension directory and the manager does not implement validateMetadata. Stored workspace/session metadata can therefore retain a path removed by the next update, undermining the stated goal of preserving affinity and restorable sessions. Add metadata validation that regenerates bundled metadata from the current extension path, and cover an old-version path in a regression test.

• minor (simplification) — ggsql-vscode/src/manager.ts:221, ggsql-vscode/src/manager.ts:782: KernelSelection exposes one eager candidate list plus a special fallback callback, which requires a second discovery branch and makes the reverse environment precedence awkward. Represent discovery as ordered lazy tiers and run one loop that stops after the first tier yielding a runnable kernel; this removes the asymmetric fallback handling and gives both strategies one precedence rule.

[georgestagg]

Will this re-download Positron for every rest run?

I think having full integration tests is a good thing, but we should try to keep an eye on how long this actually takes in CI. I'm nervous because we have had problems with both CI cache size and very long CI run times in this repo before.

[samclark2015]

Yeah, it'll re-download, but it only takes about 75s for that download + running the tests. I think leaving this uncached is best as it's a minimal time penalty, and the daily build is published often.

The biggest time sink here is building the kernel (16 mins from scratch, it seems). I added a cache restore to slurp up the deps from main to trim that time way down; but that's already written, so no cost there.