docs: update IDE integration page (#3765)

docs/ide-integration.md

@@ -1,18 +1,40 @@
 # IDE Integration
 
-IDEs work better with shims than they do environment variable modifications. The simplest way is
+Code editors and IDEs work differently than interactive shells.
-to add the mise shim directory to PATH.
+
+Usually, they will either inherit the environment from your current shell (this is the case if you start it from a terminal like `nvim .` or `code .`) or will have [their own way](https://github.com/microsoft/vscode-docs/blob/906acccd6180d8425577f8297ed29e221ad3daca/docs/supporting/faq.md?plain=1#L238) to set up the environment.
+
+Once you have launched the IDE, it won't reload the environment variables or the `PATH` provided by `mise` if you update your mise configuration files. Therefore, we cannot rely on the default `mise activate` method to automatically set up the editor.
+
+There are a few ways to make `mise` work with your editor:
+
+- Some editors or IDE plugins have direct support for `mise` and can let you select the tools/sdk path from the IDE settings. This will let you access to the tool binaries but won't load the environment variables.
+- Most editors (and language plugins) will look for tools on the `PATH` and run them in the context of your project. Therefore, adding the `mise` shims to the `PATH` might be enough (see [below](#adding-shims-to-path-default-shell)). This will run the tool provided by mise and load the environment variables.
+- In other cases, you may need to manually indicate the path to the tools provided by `mise` in the IDE settings. This can be done by using [`mise which <tool>`](./cli/which.md) or [`mise where`](./cli/where). You can also provide the path to the tool shim (e.g. `~/.local/share/mise/shims/node`) if the plugin supports it as this will also load the environment variables when the tool is run.
+- Finally, some custom plugins have been developed to work with `mise`. You can find them in the [IDE Plugins](#ide-plugins) section.
+
+## Adding shims to PATH in your default shell profile {#adding-shims-to-path-default-shell}
+
+IDEs work better with [shims](./dev-tools/shims) than they do environment variable modifications. The simplest way is
+to add the mise shim directory to `PATH`.
 
 For IntelliJ and VSCode—and likely others, you can modify your default shell's profile
 script. Your default shell can be found with:
 
-- macos – `dscl . -read /Users/$USER UserShell`
+::: code-group
-- linux – `getent passwd $USER | cut -d: -f7`
+
+```shell [macos]
+dscl . -read /Users/$USER UserShell
+```
+
+```shell [linux]
+getent passwd $USER | cut -d: -f7
+```
+
+:::
 
 You can change your default shell with `chsh -s /path/to/shell` but you may need
-to first add it to `/etc/shells`.
+to first add it to `/etc/shells`. Once you know the right one, modify the appropriate file:
-
-Once you know the right one, modify the appropriate file:
 
 ::: code-group
 
@@ -37,45 +59,33 @@ end
 
 :::
 
-This assumes that `mise` is on PATH. If it is not, you'll need to use the absolute path (
+This assumes that `mise` is on `PATH`. If it is not, you'll need to use the absolute path (
 e.g.: `eval "$($HOME/.local/bin/mise activate zsh)"`).
 
-:::: tip
+Here is an example showing that VSCode will use `node` provided by `mise`:
-Conditionally using shims is also possible. Some programs will set a `TERM_PROGRAM` environment
-variable, which may be used to determine which activation strategy to use.
 
-Here is an example using VSCode:
+::: tabs
+=== VSCode
 
-::: code-group
+[![vscode using shims](./shims-vscode.png)](./shims-vscode.png)
-
-```zsh
-# ~/.zprofile
-if [[ "$TERM_PROGRAM" == "vscode" ]]; then
-  eval "$($HOME/.local/bin/mise activate zsh --shims)"
-else
-  eval "$($HOME/.local/bin/mise activate zsh)"
-fi
-```
-
-```bash
-# ~/.bash_profile or ~/.bash_login or ~/.profile
-if [[ "$TERM_PROGRAM" == "vscode" ]]; then
-  eval "$($HOME/.local/bin/mise activate bash --shims)"
-else
-  eval "$($HOME/.local/bin/mise activate bash)"
-fi
-```
 
+=== IntelliJ
+[![intellij using shims](./shims-intellij.png)](./shims-intellij.png)
 :::
-::::
 
-This won't work for all of mise's functionality. For example, arbitrary env vars in `[env]` will
+As mentioned above, using `shims` doesn't work with all mise features. For example, arbitrary [env vars](./environments/) in `[env]` will
-only be set
+only be set if a shim is executed. For this we need tighter integration with the IDE and/or a custom plugin.
-if a shim is executed. For this we need tighter integration with the IDE and a custom plugin. If you
+
-feel
+## IDE Plugins
-ambitious, take a look at existing direnv extensions for your IDE and see if you can modify it to
+
-work for mise.
+Here are some community plugins that have been developed to work with `mise`:
-Direnv and mise work similarly and there should be a direnv extension that can be used as a starting
+
+- Emacs: [mise.el](https://github.com/liuyinz/mise.el)
+- IntelliJ: [intellij-mise](https://github.com/134130/intellij-mise)
+- VSCode: [mise-vscode](https://github.com/hverlin/mise-vscode)
+
+If you want to build a custom plugin for your editor, have a look at the existing plugins or take a look at existing direnv extensions and see if you can modify it to
+work for `mise`.`direnv` and `mise` work similarly and there should be a direnv extension that can be used as a starting
 point.
 
 ## Vim
@@ -94,7 +104,7 @@ vim.env.PATH = vim.env.HOME .. "/.local/share/mise/shims:" .. vim.env.PATH
 
 ## emacs
 
-- Traditional shims way
+### Traditional shims way
 
 ```lisp
 ;; CLI tools installed by Mise
@@ -103,13 +113,95 @@ vim.env.PATH = vim.env.HOME .. "/.local/share/mise/shims:" .. vim.env.PATH
 (setq exec-path (append exec-path '("/home/user/.local/share/mise/shims")))
 ```
 
-- Use with package [mise.el](https://github.com/liuyinz/mise.el)
+### Use with package [mise.el](https://github.com/liuyinz/mise.el)
+
+<https://github.com/liuyinz/mise.el>
+
+> A GNU Emacs library which uses the mise tool to determine per-directory/project environment variables and then set those environment variables on a per-buffer basis.
 
 ```lisp
 (require 'mise)
 (add-hook 'after-init-hook #'global-mise-mode)
 ```
 
+## JetBrains Editors (IntelliJ, RustRover, PyCharm, WebStorm, RubyMine, GoLand, etc)
+
+### IntelliJ Plugin
+
+<https://github.com/134130/intellij-mise>
+
+This plugin can automatically configure the IDE to use the tools provided by mise. It has also some support for running mise tasks and loading environment variables in the run configurations.
+
+### Direct SDK selection
+
+Some JetBrains IDEs (or language plugins) have direct support for `mise`. This allows you to select the SDK version from the IDE settings.
+Example for Java:
+
+![SDK settings](./intellij-sdk-selection.png)
+
+### SDK selection using asdf layout
+
+Some plugins cannot find SDK installed by `mise` yet but might have support for asdf.
+In that case, a workaround is to symlink the mise tool directory which has same layout as asdf:
+
+```sh
+ln -s ~/.local/share/mise ~/.asdf
+```
+
+Then they should show up on in Project Settings:
+
+![project settings](https://github.com/jdx/mise-docs/assets/216188/b34a0e3f-7af8-45c9-85b8-2c72bd1dc226)
+
+Or in the case of node (possibly other languages), it's under "Languages & Frameworks":
+
+![languages & frameworks](https://github.com/jdx/mise-docs/assets/216188/9926be1c-ab88-451a-8ace-edf2dac564b5)
+
+## VSCode
+
+### VSCode Plugin
+
+There is a [VSCode plugin](https://marketplace.visualstudio.com/items?itemName=hverlin.mise-vscode) which can configure other extensions for you, without having to modify your shell profile to add the shims to `PATH`.
+
+In addition, it provides additional features such as:
+
+- Automatic configuration of other extensions to use tools provided by `mise`
+- Manage `mise` tasks, tools, and environment variables directly from VSCode
+- Load environment variables from `mise.toml` files in VSCode
+- Support for autocompletion and snippets for `mise.toml` file
+- Integration with VSCode tasks
+
+<https://github.com/hverlin/mise-vscode/> ([Documentation](https://hverlin.github.io/mise-vscode/))
+
+### Use [`mise exec`](./cli/exec) in launch Configuration
+
+While modifying your default shell profile is likely the easiest solution, you can also set
+the tools in `launch.json`:
+
+::: details mise exec launch.json example
+
+```json
+{
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Launch Program",
+      "program": "${file}",
+      "args": [],
+      "osx": {
+        "runtimeExecutable": "mise"
+      },
+      "linux": {
+        "runtimeExecutable": "mise"
+      },
+      "runtimeArgs": ["exec", "--", "node"]
+    }
+  ]
+}
+```
+
+:::
+
 ## Xcode
 
 Xcode projects can run system commands from script build phases and schemes. Since Xcode sandboxes
@@ -126,50 +218,6 @@ eval "$($HOME/.local/bin/mise activate -C $SRCROOT bash --shims)"
 swiftlint
 ```
 
-## JetBrains Editors (IntelliJ, RustRover, PyCharm, WebStorm, RubyMine, GoLand, etc)
-
-Some JetBrains IDEs have direct support for mise, others have support for asdf which can be used by
-first symlinking the mise tool directory which is the
-same layout as asdf:
-
-```sh
-ln -s ~/.local/share/mise ~/.asdf
-```
-
-Then they should show up on in Project Settings:
-
-![project settings](https://github.com/jdx/mise-docs/assets/216188/b34a0e3f-7af8-45c9-85b8-2c72bd1dc226)
-
-Or in the case of node (possibly other languages), it's under "Languages & Frameworks":
-
-![languages & frameworks](https://github.com/jdx/mise-docs/assets/216188/9926be1c-ab88-451a-8ace-edf2dac564b5)
-
-## VSCode
-
-While modifying `~/.zprofile` is likely the easiest solution, you can also set
-the tools in `launch.json`:
-
-```json
-{
-  "configurations": [
-    {
-      "type": "node",
-      "request": "launch",
-      "name": "Launch Program",
-      "program": "${file}",
-      "args": [],
-      "osx": {
-        "runtimeExecutable": "mise"
-      },
-      "linux": {
-        "runtimeExecutable": "mise"
-      },
-      "runtimeArgs": ["x", "--", "node"]
-    }
-  ]
-}
-```
-
 ## [YOUR IDE HERE]
 
 I am not a heavy IDE user. I use JetBrains products but I don't actually