Mason

Mason installs anything that isn’t a Neovim plugin — LSP servers, formatters, linters, the tree-sitter CLI, debuggers. Blak wires it so the tools an extra needs install automatically when you enable the extra.

Tools setup: lua/blak/core/tools.lua. Plugin spec: lua/blak/plugins/lsp.lua.

Defaults

mason = {
  automatic_install = true,
  ensure_installed = {
    "stylua",
    "shfmt",
    "tree-sitter-cli",
  },
}

Just enough to make first-launch useful: a Lua formatter (for the config files Blak ships), a shell formatter, and the CLI for compiling Treesitter parsers.

Extras add to this list automatically — see each extra’s “Mason” row in Extras.

Automatic install

When automatic_install = true, Blak calls tools.ensure() after Mason wakes on VeryLazy, :Mason, or the first Mason-backed LSP buffer:

1. Wait for the Mason registry to refresh.
2. Look up the configured package list (mason.ensure_installed + extras).
3. Install anything missing.
4. Skip anything already installed (silent), or log it if called with force = true.

When ts_ls is configured, Blak also checks the TypeScript runtime inside Mason’s typescript-language-server package. An installation missing tsserver.js or package metadata is repaired even when Mason still has an installation receipt. Wait for completion and restart to retry failed clients. This repair follows automatic_install; :BlakToolsInstall requests it manually.

Missing packages don’t error — they warn so a typo or a Mason-renamed tool doesn’t block startup.

A failed install warns too: Could not install Mason package <name>: <reason>. See :MasonLog. :MasonLog has the installer output. Common causes are a missing runtime such as Python, Node.js, or Go, or a package Mason does not ship for your platform. :checkhealth blak lists every configured tool that is still not installed.

Manual install

:BlakToolsInstall      " force, logs already-installed packages too
:Mason                 " open Mason's UI
:MasonInstall <pkg>    " install one explicitly

Use :BlakToolsInstall after enabling a new extra so its tools land in one shot.

Disabling automatic install

return {
  mason = { automatic_install = false },
}

You’ll need to install tools yourself with :BlakToolsInstall or :Mason.

Adding a tool

In user.lua:

return {
  mason = {
    ensure_installed = { "stylua", "shfmt", "tree-sitter-cli", "buf", "yamlfmt" },
  },
}

Like other lists, this replaces the default wholesale. Include the defaults you still want.

Or via an extra, so its configuration is removed when you disable it and restart. Installed tools remain in Mason until you explicitly uninstall them.

Mason UI

The Mason UI uses your ui.winborder (default "rounded"). Open with :Mason. From there:

• i install
• u update
• X uninstall
• ? help

Where things live

$XDG_DATA_HOME/<appname>/mason/        " for Blak, usually ~/.local/share/blak/mason
  ├── packages/<name>/                 " installed binaries / scripts
  └── bin/                             " shims added to runtime $PATH

mason-lspconfig bridges between Mason package names (lua-language-server) and lspconfig server names (lua_ls). The ensure_installed list it sends to Mason is derived from lsp.servers keys. Only configured servers are automatically enabled; Blak enables them whether or not Mason installed them, so servers on $PATH work too. mason.automatic_install = false disables automatic installation of both tools and language servers; :BlakToolsInstall explicitly requests both.