jochen
75f25fca21
Slack comes from the AUR and Toolbox from JetBrains' self-updating tarball, so neither is declared: the host installs official packages only, and a pinned archive would fight Toolbox's own updates. Slack's start and the operator's i3 window rules become one node-display-session contribution, because Slack's own launch-on-login is a symlink in ~/.config/autostart. Toolbox keeps its own autostart entry as its one start. The shared desktop.go header now names all four bundles.
120 lines
8.6 KiB
Markdown
120 lines
8.6 KiB
Markdown
# jetbrains-toolbox
|
|
|
|
JetBrains Toolbox on the workstations, as a module (novox/hq ADR 0208). Toolbox installs, updates and
|
|
launches the JetBrains IDEs. It requires `x11-display`, so it is assigned only where a display server
|
|
is held on the same machine.
|
|
|
|
## Owns
|
|
|
|
Nothing on disk. It holds no seat, makes no contribution and writes no file. What it owns is the rule
|
|
that Toolbox has **one start**, and the tools that see Toolbox and its IDEs.
|
|
|
|
- **Not a package.** The distribution does not package Toolbox. JetBrains ships a tarball, which the
|
|
operator unpacked once. Toolbox keeps itself in `~/.local/share/JetBrains/Toolbox`:
|
|
- its launcher and runtime, in `bin/`;
|
|
- the IDEs, in `apps/`;
|
|
- its settings, state and update channels, in `.settings.json`, `state.json` and `channels/`;
|
|
- its account, in `accounts.json` and `.securestorage`;
|
|
- its logs.
|
|
- **Kept as found, not a pinned archive (ADR 0205).** ADR 0205 ships software the distribution lacks as
|
|
a pinned archive of the module's own. Toolbox is the exception it does not foresee:
|
|
- it **updates itself in place**, and it updates the IDEs. A pinned copy would be a second writer of
|
|
`bin/`: either the push rolls Toolbox back after every self-update, or Toolbox overwrites the
|
|
mesh's copy;
|
|
- its licence is JetBrains', not one the mesh's store may redistribute.
|
|
|
|
So the module installs nothing. The operator installs Toolbox once, by its own instructions
|
|
(`Install-linux-tar.txt` beside the launcher), and Toolbox keeps itself current. `toolbox_check`
|
|
says when it is missing.
|
|
- **Toolbox's files are found** (ADR 0182). The module never declares, writes or removes any of them.
|
|
The tools read the version, the switches, the tool list and the channels. They never read the
|
|
account, the secure storage or the logs.
|
|
|
|
## How it starts: Toolbox's own autostart entry, and nothing else
|
|
|
|
One process has one starter (the rule `picom` states for the desktop modules). Toolbox's starter is
|
|
**its own XDG autostart entry**, `~/.config/autostart/jetbrains-toolbox.desktop`
|
|
(`…/bin/jetbrains-toolbox --minimize`).
|
|
|
|
- Toolbox writes that entry while its setting *Launch Toolbox App at system startup* is on, and
|
|
removes it when the setting is off. The setting is `autostart` in `.settings.json`; absent means on,
|
|
Toolbox's default.
|
|
- The session runs every XDG autostart entry once at login: the `i3` module's
|
|
`dex --autostart --environment i3`.
|
|
|
|
**Why not a contribution to `node-display-session`:** Toolbox would still write its own entry
|
|
whenever the setting is on, and the session would start it twice. The module cannot own the entry
|
|
either: Toolbox rewrites it, and that would be two writers. So, as `nextcloud-client` does, the module
|
|
adds no start, and `toolbox_check` holds the rule:
|
|
|
|
- the entry exists exactly when the setting says so;
|
|
- no window-manager `exec` starts Toolbox as well.
|
|
|
|
**Off is an answer, not a fault.** With the setting off, Toolbox does not start at login and runs
|
|
when the operator opens it (from the launcher, or a `jetbrains://` link). `toolbox_check` notes that
|
|
and finds nothing wrong.
|
|
|
|
## Tools
|
|
|
|
They are served by the node's runtime as the operator account (ADR 0175), and are read-only except
|
|
`restart`. **No answer carries the JetBrains account**: neither its id nor anything from
|
|
`accounts.json` or `.securestorage`. Paths under the home are answered as `~/…`.
|
|
|
|
| tool | does |
|
|
|---|---|
|
|
| `toolbox_status` (r) | <ul><li>whether Toolbox is installed, its version (`bin/build.txt`) and the version its state was last written by</li><li>whether it runs: pid, since, and the unit or scope</li><li>what starts it at login</li><li>its switches: launch at login (and whether that is the default), update the tools automatically, the shell scripts' folder, the theme, how many versions it keeps for a rollback</li><li>every tool it installed: name, version, build, **update channel** (Release, Early Access Program …), whether that tool updates itself, where it is and whether it is on disk</li><li>any directory under `apps/` that its list does not name</li></ul> |
|
|
| `toolbox_restart` (a) | ends Toolbox (SIGTERM, forced after 8 s) and starts `…/bin/jetbrains-toolbox --minimize` in the operator's session. The start is a transient user unit `mesh-jetbrains-toolbox`, so it outlives the tools runtime. The IDEs Toolbox launched are their own processes and keep running. Answers the pids. Refused plainly when nobody is logged in to the desktop, or when Toolbox is not installed |
|
|
| `toolbox_check` (r) | <ul><li>Toolbox is installed</li><li>at most one start: the entry is there exactly when the setting is on, it runs Toolbox, `dex` is installed, and no window-manager exec</li><li>at most one Toolbox runs, and one runs when it starts at login</li><li>every tool in its list is on disk</li></ul>Each finding says what to do. Notes cover the setting being off, and directories it does not list |
|
|
|
|
**Which process is Toolbox:** the kernel keeps 15 characters of a process's name, so Toolbox's comm
|
|
is `jetbrains-toolb`. A process with that comm counts only when its command is Toolbox's launcher.
|
|
**The bundle is named `toolbox-tools`, not `jetbrains-toolbox-tools`.** The longer name cuts to the
|
|
same comm, and `toolbox_restart` would have ended the tools themselves.
|
|
|
|
The tools find the session's `DISPLAY` and `XAUTHORITY` from the window manager's own environment,
|
|
as the other desktop modules do. Every command has a timeout and capped output. Everything runs through
|
|
an injected runner and a fake root in the tests.
|
|
|
|
## What changes when it is assigned
|
|
|
|
| | g14 | shanks |
|
|
|---|---|---|
|
|
| Toolbox | none: Toolbox 2.8.1.52155 in `~/.local/share/JetBrains/Toolbox` (tarball install), not running. Its files are from 2025-09-04, the last time it ran, so it has not updated itself or the IDEs since | none: Toolbox 3.2.0.65851, the same place (`.installation-type` says `APP`), last run 2026-02-23; not running |
|
|
| start | none: *Launch at startup* is **off** (`autostart: false`) and there is no entry, so nothing starts it at login. `toolbox_check`: ok, with a note | none on disk: the setting is at its default (on), and Toolbox's own entry (`--minimize`) is there. The `i3` module's dex starts it at the next login. The session running now (since 2026-10-04) began before dex was installed, which is why Toolbox does not run. `toolbox_check` names that until `toolbox_restart` or the next login |
|
|
| IDEs | Fleet 1.48.261, PyCharm 2025.2.1.1, Rider 2025.2.0.1, WebStorm 2025.2.2: all on the **Early Access Program** channel | RustRover 2026.1 EAP and Fleet 1.48.261 on **Early Access Program**; PyCharm 2025.3.2.1, Rider 2025.3.2 and WebStorm 2025.3.2 on **Release** |
|
|
| updates | update the tools automatically: on | the same; one version kept for a rollback |
|
|
|
|
The two machines differ in Toolbox's major version and in the IDEs' channels. Both are the
|
|
operator's choices in Toolbox, and the module reports them rather than aligning them.
|
|
|
|
## Migration (ADR 0182)
|
|
|
|
Nothing is required on either machine. The module removes nothing and adds no start.
|
|
|
|
- **shanks:** run `toolbox_restart`, or log out and in, and Toolbox runs from its one start.
|
|
`toolbox_check` then answers `ok`. Toolbox wrote its entry with the executable bit set (0744), which
|
|
systemd's autostart generator warns about at every login. That is harmless under i3, and the entry
|
|
is Toolbox's, so the module leaves it.
|
|
- **g14:** nothing. To have Toolbox start at login there too, open it and tick *Launch Toolbox App at
|
|
system startup*. It writes its own entry, and it then updates itself and the IDEs, which it has not
|
|
done since 2025-09.
|
|
- **Not the module's:** `~/.profile` on g14 adds Toolbox's `scripts/` folder to `PATH` by hand. The
|
|
account's environment is `node-environment`'s holder's. If the IDE launch scripts are wanted on
|
|
`PATH` on both machines, that is a contribution to it, not a line in `~/.profile`.
|
|
|
|
## Leaves as found
|
|
|
|
- `~/.local/share/JetBrains/Toolbox/`, entirely: the launcher, the runtime, the IDEs, the settings,
|
|
the state, the account, the logs, and the link Toolbox itself keeps in `scripts/` for Fleet.
|
|
- `~/.config/autostart/jetbrains-toolbox.desktop`, Toolbox's own.
|
|
- The desktop entries Toolbox writes for itself and each IDE in `~/.local/share/applications/`. Those
|
|
include `jetbrainsd.desktop` on shanks.
|
|
- The `x-scheme-handler/jetbrains` default, which is the `xdg` module's.
|
|
|
|
## Relies on
|
|
|
|
- **`i3`'s `dex` line for the start.** Nothing in the mesh says so yet: XDG autostart has no seat, and
|
|
a module without a seat or contribution has no way to depend on another module. Assigned without
|
|
`i3`, Toolbox is not started at login. `toolbox_check` says so when its setting is on.
|
|
- A display server on the same machine (`x11-display`, ADR 0208 §3).
|