Skip to content

Find and run the language server and the CLI everywhere, Flatpak included - #33

Merged
Kinflou merged 10 commits into
mainfrom
fix/server-and-cli-resolution
Nov 15, 2026
Merged

Kinflou merged 10 commits into
mainfrom
fix/server-and-cli-resolution

Conversation

@Kinflou

@Kinflou Kinflou commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

Closes #29. Closes #30.

What changed

Resolution (src/resolve.ts, new). Pure code with no vscode import: PATH lookup, Flatpak detection, the plan for each mode, and the command line. extension.ts supplies the real file system and runs the result.

  • path (server and CLI): the name is looked up on process.env.PATH, with PATHEXT on Windows (Server mode "path" never finds comline-lsp: existsSync checks the cwd, not PATH #29). The old check was fs.existsSync('comline-lsp'), which reads the cwd. The error lists the directories searched. A custom path with no directory in it is looked up the same way.
  • host (new value of comline.server.mode and comline.cli.mode): runs the program through flatpak-spawn --host. The server keeps stdio piped (Executable with command: flatpak-spawn, args: ["--host", "--watch-bus", "--env=RUST_LOG=debug", "comline-lsp"]). --env= carries RUST_LOG, since the host command doesn't get the sandbox's environment. --watch-bus ends the host process with flatpak-spawn, so the server doesn't outlive the editor. The CLI task passes CLICOLOR_FORCE the same way.
  • comline.server.customPath / comline.cli.customPath name the program to run in host mode when set (an absolute host path, for a binary on no PATH the host session has, e.g. ~/.cargo/bin). Outside a Flatpak, host is the same as path/custom, so a synced settings file works on every machine.
  • Before running through flatpak-spawn, the extension checks that flatpak-spawn exists in the sandbox and asks the host's shell (command -v) whether the program is there. It then reports one of: what to install and which setting to change; or that flatpak-spawn --host itself failed (stderr passed on, with the --talk-name=org.freedesktop.Flatpak override to grant).
  • The program name is passed as a positional argument to sh -c 'command -v "$1"', never spliced into the script.

Default inside a Flatpak. comline.server.mode stays bundled; comline.cli.mode stays path. Inside a Flatpak, path now means the host, for both.

  • The bundled Linux servers are static musl builds that run in the sandbox (the README said so), so the server's default needs no flatpak-spawn, no D-Bus permission, and nothing installed on the host. Making host the default would turn a working default into one that can fail.
  • The CLI is not bundled, and the sandbox's PATH can't see a host-installed comline, so for the CLI path could only ever fail in a Flatpak. Mapping it to the host makes the default work and needs no new setting.
  • custom inside a Flatpak is run as written in the sandbox, as before. If the file isn't there, the message says why (the host's /usr etc. are reserved) and to use host.
  • I did not use "mode unset": a default and an unset setting are the same thing for config.get, and keying on it would make behaviour depend on whether the user ever saved the value.

CLI commands (#30). Generate runs comline generation and Clean runs comline generation clean. I checked ComlineProject/cli main (src/cli.rs, docs/cli.md): Generation (visible alias gen) has the subcommand Clean; the top-level Generate/Clean are gone; Targets is unchanged, so the code-generation target completion keeps working. I used the full name generation over the alias. Command ids (comline.generate, comline.clean) and titles are unchanged, so keybindings keep working. These commands now need a CLI with cli#153. The status bar menu uses the same subcommands.

Also fixed. Build/Check/Generate/Clean/Select Package were registered after the server lookup, so a server that wasn't found removed them (command not found). They're registered first now.

Docs. package.json: host in both enums, with descriptions; customPath descriptions say what they do in host mode. README: the Flatpak workaround section is now the short version (automatic, or one setting), with the custom-path and /usr caveat kept. CHANGELOG: Unreleased entries.

Tests. There was no test setup. yarn test (node --test, Node's built-in runner, no new dependency) runs src/resolve.test.ts after yarn compile: PATH lookup (order, empty entries, cwd not searched, a path as written, Windows Path/PATHEXT), Flatpak detection, each mode's plan inside and outside a Flatpak, command and argument construction (stdio, --env, --watch-bus), host probe results, and the messages. It's a step of the Package Test job. .vscodeignore keeps out/**/*.test.js out of the .vsix.

Flatpak references

  • flatpak-spawn --host: "Run the command unsandboxed on the host. This requires access to the org.freedesktop.Flatpak D-Bus interface." Also --env=VAR=VALUE, --watch-bus, --directory (flatpak-spawn, source).
  • FLATPAK_ID is set to the app's id in the sandbox (flatpak run, Environment); /.flatpak-info is the instance's metadata (flatpak metadata). Either marks a Flatpak.
  • --filesystem=host mounts the host's /usr, /bin, /sbin, /lib* (host-os) at /run/host, not at /usr; /usr, /etc, /bin, /lib, /run/host and others are reserved and a --filesystem for them has no effect (sandbox permissions, "Reserved Paths").
  • Both Flathub manifests, read at master, have --filesystem=host and --talk-name=org.freedesktop.Flatpak: com.vscodium.codium, com.visualstudio.code. They don't differ on these. The VS Code one also bundles host-spawn (a separate tool the extension doesn't use) and adds --talk-name=org.freedesktop.Notifications.

Flatpak end-to-end (.github/workflows/flatpak.yml)

Runs the extension's real resolution (out/resolve.js, with systemProbe(): the real file system and environment) inside Flathub's real com.vscodium.codium sandbox, headless (flatpak run --command=/app/share/codium/com.vscodium.codium --env=ELECTRON_RUN_AS_NODE=1), under dbus-run-session, against a real flatpak-spawn --host. scripts/flatpak-e2e.cjs has the scenarios; each is an assertion that fails the job:

  1. bundled: the static comline-lsp runs in the sandbox and answers initialize over stdio.
  2. host: comline-lsp runs on the host (by name; by an absolute path in the host-only /usr/local/bin; by an absolute path in the home directory) and answers initialize. With debug on, RUST_LOG=debug is in the host process's /proc/<pid>/environ, and absent without it. The host process's exe is the host binary. A clean stop ends it; killing flatpak-spawn ends it.
    • comline-lsp also exits when its stdin closes, so that alone doesn't prove --watch-bus. Scenario 2d uses sleep on the host, which ignores stdin: with --watch-bus it ends when flatpak-spawn is killed, and the control without it keeps running.
  3. host probe: ok when present, missing when not, failed (with the reason) when flatpak-spawn can't reach the session bus; and the message the extension shows for a missing program.
  4. path mode in the sandbox resolves to a host plan, for the server and the CLI.
  5. custom under the host's /usr is an error that names host mode. The file is shown to be visible on the host and not in the sandbox.
  6. CLI in host mode: comline --path <package> generation and generation clean, through the launch the extension builds, write and remove the generated code on disk; comline targets runs; the old generate fails.

Set-up and exceptions:

  • The sandbox job runs in ghcr.io/comlineproject/ci-flatpak (Add ci-flatpak: Flatpak's sandbox and Flathub's VSCodium at pinned commits ci-images#8), pinned by digest, with --privileged because bubblewrap creates namespaces. The image holds Debian's flatpak, bubblewrap and xdg-dbus-proxy (apt pinned by a snapshot.debian.org timestamp) and Flathub's com.vscodium.codium with its runtime, each at a pinned commit. Nothing is installed or cached while the job runs. The job logs both commits. The image's own checks confirm the app still has --filesystem=host and --talk-name=org.freedesktop.Flatpak. Moving to a newer VSCodium is a deliberate commit bump in ci-images, then a digest bump here.
  • comline-lsp is built in this workflow from comline.languageServer.rev in package.json, as the same static musl build release.yml bundles, so the test runs exactly what the next release ships. The sandbox job logs its sha256, which matches the build job's. comline (the CLI) has no release yet: it is built from a pinned ComlineProject/cli commit (e79092a, static musl, Rust generator only) in the CI tools image.
  • The weekly run now only catches changes to the runner, kernel or AppArmor, since nothing else moves under the job.
  • Triggers: pull requests and pushes to main touching src/resolve.ts, src/extension.ts, package.json, the workflow or the script; weekly; manual.

Not verified

  • The VS Code Flathub app (com.visualstudio.code) is not run: only VSCodium is. Their manifests agree on the two permissions this needs.
  • All scenarios passed on their first run in the sandbox, so none has been seen failing for a code reason (nothing in Find and run the language server and the CLI everywhere, Flatpak included #33 needed fixing); scenario 2d's control (the unwatched sleep survives) is what shows a check there can fail.
  • The host command's PATH being the session's: the e2e exports ~/.local/bin into the environment dbus-run-session starts the helper in, which is the behaviour described; a real desktop session's PATH is not tested.

Kinflou added 9 commits November 16, 2026 01:50
…uded

path mode looked the bare name up with fs.existsSync, which checks the
current directory, so it never found anything (#29). The name is now
resolved against PATH (PATHEXT on Windows), and the error lists the
directories searched. The CLI resolves the same way.

A host mode for comline.server.mode and comline.cli.mode runs the program
on the host through flatpak-spawn --host, with stdio piped and RUST_LOG
passed as --env. Inside a Flatpak, path mode does this on its own, since
the sandbox's PATH is not the host's. flatpak-spawn and the program on the
host are checked first, and the message says what to install or which
setting to change.

Generate and Clean run comline generation and comline generation clean,
as cli#153 renamed them (#30). The command ids are unchanged.

The CLI commands are registered before the server is looked up, so a
missing server no longer takes them away. The resolution is in
src/resolve.ts, free of vscode, with unit tests run by yarn test in the
Package Test job.
A workflow that installs com.vscodium.codium from Flathub on an Ubuntu VM
and runs out/resolve.js inside it, with a real flatpak-spawn --host: the
bundled server in the sandbox, host mode (by name, by a path in the host's
/usr, by a path in the home directory, RUST_LOG, --watch-bus), the host
probe, path and custom resolution, and the CLI's generation and
generation clean on disk.

The system probe and the host check move into resolve.ts so the extension
and the test run the same code.
@Kinflou
Kinflou marked this pull request as ready for review November 15, 2026 20:09
@Kinflou
Kinflou merged commit 6253b61 into main Nov 15, 2026
33 checks passed
@Kinflou
Kinflou deleted the fix/server-and-cli-resolution branch November 15, 2026 20:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant