Tom Boucher 792b166ce6 fix: improve LSP diagnostics when no servers detected (#1082 ) (#1086 )

* docs: add Node LTS pinning guide for macOS Homebrew users

New doc (docs/node-lts-macos.md) explains how to pin Node 24 LTS
via Homebrew to avoid running on odd-numbered development releases.
Covers brew install/link/pin, version managers as alternatives,
and verification steps.

Added notice banner in README linking to the guide.

* fix: improve LSP diagnostics when no servers detected (#1082)

When lsp status returns 'No language servers configured', the output
now includes diagnostics:
- Which project markers were detected (e.g. package.json found)
- Which server commands are missing (e.g. typescript-language-server)
- Install instructions

Also added LSP troubleshooting section to docs/troubleshooting.md
with common install commands per language.

2026-03-17 21:45:11 -06:00

1.9 KiB

Raw Blame History

Pinning Node.js LTS on macOS with Homebrew

If you installed Node.js via Homebrew (brew install node), you're tracking the latest current release — which can include odd-numbered development versions (e.g. 23.x, 25.x). These aren't LTS and may have breaking changes or instability.

GSD requires Node.js v22 or later and works best on an LTS (even-numbered) release. This guide shows how to pin Node 24 LTS using Homebrew.

Check your current version

node --version

If this shows an odd number (e.g. v23.x, v25.x), you're on a development release.

Install Node 24 LTS

Homebrew provides versioned formulas for LTS releases:

# Unlink the current (possibly non-LTS) version
brew unlink node

# Install Node 24 LTS
brew install node@24

# Link it as the default
brew link --overwrite node@24

Verify:

node --version
# Should show v24.x.x

Why pin to LTS?

Stability — LTS releases receive bug fixes and security patches for 30 months
Compatibility — npm packages (including GSD) test against LTS versions
No surprises — brew upgrade won't jump you to an unstable development release

Prevent accidental upgrades

By default, brew upgrade will upgrade all packages, which could move you off the pinned version. Pin the formula:

brew pin node@24

To unpin later:

brew unpin node@24

Switching between versions

If you need multiple Node versions (e.g. 22 and 24), consider using a version manager instead:

nvm — nvm install 24 && nvm use 24
fnm — fnm install 24 && fnm use 24 (faster, Rust-based)
mise — mise use node@24 (polyglot version manager)

These let you set per-project Node versions via .node-version or .nvmrc files.

Verify GSD works

After pinning:

node --version   # v24.x.x
npm install -g gsd-pi
gsd --version

1.9 KiB Raw Blame History