glaze.nvim/AGENTS.md

AGENTS.md

AI agent guide for working in glaze.nvim.

Project Overview

glaze.nvim is a Neovim plugin that provides centralized management for Go binaries used by other Neovim plugins. Think "Mason for Go binaries" with a lazy.nvim-style UI.

• Language: Lua (Neovim plugin)
• Requirements: Neovim >= 0.9, Go installed
• Author: Tai Groot (taigrr)

Directory Structure

lua/glaze/
├── init.lua      # Main module: setup, config, registration API, binary path utilities
├── runner.lua    # Task runner: parallel go install with concurrency control
├── checker.lua   # Update checker: version comparison, auto-check scheduling
├── view.lua      # UI: lazy.nvim-style floating window, keybinds, rendering
├── float.lua     # Float window abstraction: backdrop, keymaps, resize handling
├── text.lua      # Text rendering: buffered text with highlight segments
├── colors.lua    # Highlight definitions: doughnut-inspired pink/magenta theme
├── health.lua    # Health check: :checkhealth glaze
doc/
└── glaze.txt     # Vim help documentation

Key Concepts

Binary Registration

Plugins register binaries via require("glaze").register(name, url, opts). Registration stores metadata in M._binaries table. Auto-install triggers if enabled and binary is missing.

Task Runner

runner.lua manages parallel go install jobs with configurable concurrency. Tasks have states: pending → running → done|error. The runner opens the UI automatically when tasks start.

Update Checking

checker.lua compares installed versions (go version -m) against latest (go list -m -json). State persisted to vim.fn.stdpath("data") .. "/glaze/state.json".

UI Architecture

• float.lua: Generic floating window with backdrop (inspired by lazy.nvim)
• view.lua: Glaze-specific rendering, keybinds, spinner animation
• text.lua: Buffered text builder with highlight segments and extmarks

Commands

Command	Description
:Glaze	Open the UI
:GlazeUpdate [name]	Update all or specific binary
:GlazeInstall [name]	Install missing or specific binary
:GlazeCheck	Manual update check
:checkhealth glaze	Run health check

Testing

No automated tests exist. Manual testing workflow:

-- In Neovim:
:luafile %              -- Reload current file
:Glaze                  -- Test UI
:checkhealth glaze      -- Verify setup

Test with actual binaries:

require("glaze").setup({})
require("glaze").register("glow", "github.com/charmbracelet/glow")
:GlazeInstall glow

Code Conventions

Module Pattern

All modules return a table M with public functions. Private functions prefixed with _:

local M = {}
M._private_state = {}
function M.public_fn() end
function M._private_fn() end
return M

Type Annotations

Uses LuaCATS (---@class, ---@param, ---@return) for type hints. LSP warnings about vim being undefined are expected (Neovim globals).

Async Patterns

• vim.fn.jobstart() for external commands
• vim.schedule() to defer to main loop
• vim.defer_fn() for delayed execution

UI Updates

• Runner notifies via M._on_update callback
• View subscribes and re-renders on notification
• Timer drives spinner animation (100ms interval)

Highlight Groups

All highlights prefixed with Glaze. Key groups:

• GlazeH1, GlazeH2 - Headers
• GlazeBinary, GlazeUrl, GlazePlugin - Content
• GlazeDone, GlazeError, GlazeRunning - Status
• GlazeProgressDone, GlazeProgressTodo - Progress bar

Colors follow doughnut aesthetic (pink #FF6AD5 as primary accent).

Configuration

Default config in init.lua:53-78. Key options:

• concurrency: Parallel jobs (default 4)
• auto_install.enabled: Install on register
• auto_check.enabled/frequency: Update checking
• auto_update.enabled: Auto-apply updates

Common Tasks

Adding a New Config Option

1. Add to GlazeConfig type definition in init.lua
2. Add default value in M.config
3. Document in README.md and doc/glaze.txt

Adding a New Command

1. Create in M.setup() via vim.api.nvim_create_user_command()
2. Document in README and help file

Modifying UI

1. Edit view.lua:render() for content changes
2. Edit view.lua:open() to add keybinds
3. Edit colors.lua for new highlight groups

Adding Health Checks

Add checks in health.lua:check() using vim.health.ok/warn/error/info.

Gotchas

1. vim global: All vim.* calls show LSP warnings - this is normal for Neovim plugins without proper Lua LSP config.

2. Race conditions: runner.lua rejects new tasks if already running. Check runner.is_running() first.

3. Timer cleanup: view.lua._timer must be stopped on close, or spinner keeps running.

4. State file: checker.lua persists to data dir. If corrupt, delete ~/.local/share/nvim/glaze/state.json.

5. GOBIN detection: Checks multiple locations: $GOBIN, $GOPATH/bin, ~/go/bin. See init.lua:is_installed().

6. goenv support: Auto-detected in setup, changes go_cmd to { "goenv", "exec", "go" }.

API Reference

Main module (require("glaze")):

• setup(opts) - Initialize with config
• register(name, url, opts) - Register binary
• unregister(name) - Remove binary
• binaries() - Get all registered
• is_installed(name) - Check if binary exists
• bin_path(name) - Get full path
• status(name) - Get "installed"/"missing"/"unknown"

Runner (require("glaze.runner")):

• update(names) / update_all() - Update binaries
• install(names) / install_missing() - Install binaries
• abort() - Stop all tasks
• is_running() / tasks() / stats() - Query state

Checker (require("glaze.checker")):

• check(opts) - Check for updates
• auto_check() - Check if interval passed
• get_update_info() - Get cached version info