*glaze.txt*  🍩 Centralized Go binary management for Neovim plugins

Author:   Tai Groot <tai@taigrr.com>
License:  0BSD
Homepage: https://github.com/taigrr/glaze.nvim

==============================================================================
CONTENTS                                                      *glaze-contents*

  1. Introduction ........................... |glaze-introduction|
  2. Setup .................................. |glaze-setup|
  3. Commands ............................... |glaze-commands|
  4. Keybinds ............................... |glaze-keybinds|
  5. API .................................... |glaze-api|
  6. Configuration .......................... |glaze-config|
  7. Highlights ............................. |glaze-highlights|
  8. Auto-update Checking ................... |glaze-auto-check|
  9. For Plugin Authors ..................... |glaze-plugin-authors|

==============================================================================
1. INTRODUCTION                                           *glaze-introduction*

Glaze (Go + Lazy = Glaze 🍩) is a centralized manager for Go binaries used by
Neovim plugins. Instead of each plugin implementing its own binary installer,
Glaze provides:

- A unified lazy.nvim-style UI for managing all Go binaries
- Parallel installation with progress tracking
- Cursor-aware keybinds for individual binary control
- Automatic update checking with notifications
- GOBIN/GOPATH awareness
- A simple registration API for plugin authors

==============================================================================
2. SETUP                                                        *glaze-setup*

Using lazy.nvim:
>lua
  {
    "taigrr/glaze.nvim",
    config = function()
      require("glaze").setup({})
    end,
  }
<

==============================================================================
3. COMMANDS                                                  *glaze-commands*

                                                                      *:Glaze*
:Glaze                  Open the Glaze UI window.

                                                                *:GlazeUpdate*
:GlazeUpdate [name]     Update all registered binaries, or a specific one.

                                                               *:GlazeInstall*
:GlazeInstall [name]    Install missing binaries, or a specific one.

                                                                *:GlazeCheck*
:GlazeCheck             Manually check for available updates.

==============================================================================
4. KEYBINDS                                                  *glaze-keybinds*

These keybinds are active in the Glaze UI window:

  Key         Action ~
  `U`           Update ALL registered binaries
  `u`           Update the binary under the cursor
  `I`           Install all missing binaries
  `i`           Install the binary under the cursor
  `x`           Abort all running tasks
  `<CR>`        Toggle detail expansion (URL, path, version, errors)
  `q`           Close the Glaze window
  `<Esc>`       Close the Glaze window

==============================================================================
5. API                                                            *glaze-api*

                                                            *glaze.setup()*
glaze.setup({opts})
    Initialize Glaze with optional configuration.

                                                         *glaze.register()*
glaze.register({name}, {url}, {opts?})
    Register a binary for management.

    Parameters: ~
      {name}  Binary/executable name (string)
      {url}   Go module URL without version (string)
      {opts}  Optional table with:
              - plugin: Name of the registering plugin (string)
              - callback: Function called after install/update (function)

                                                       *glaze.unregister()*
glaze.unregister({name})
    Remove a binary from management.

                                                         *glaze.binaries()*
glaze.binaries()
    Returns all registered binaries as a table.

                                                     *glaze.is_installed()*
glaze.is_installed({name})
    Returns true if the binary is found in PATH, $GOBIN, $GOPATH/bin,
    or ~/go/bin.

                                                        *glaze.bin_path()*
glaze.bin_path({name})
    Returns the full path to the binary, or nil if not found.

                                                           *glaze.status()*
glaze.status({name})
    Returns "installed", "missing", or "unknown".

                                                        *glaze-runner-api*
Runner API (require("glaze.runner")):

  runner.update({names})       Update specific binaries
  runner.update_all()          Update all registered binaries
  runner.install({names})      Install specific binaries
  runner.install_missing()     Install all missing binaries
  runner.abort()               Stop all running tasks
  runner.is_running()          Check if tasks are running
  runner.tasks()               Get current task list
  runner.stats()               Get task statistics
  runner.on_update({fn})       Register callback for task state changes

                                                       *glaze-checker-api*
Checker API (require("glaze.checker")):

  checker.check()              Check for updates (with notifications)
  checker.auto_check()         Check only if enough time has passed
  checker.get_update_info()    Get cached update info table

==============================================================================
6. CONFIGURATION                                              *glaze-config*

Default configuration:
>lua
  require("glaze").setup({
    ui = {
      border = "rounded",
      size = { width = 0.7, height = 0.8 },
      icons = {
        pending = "○",
        running = "◐",
        done = "●",
        error = "✗",
        binary = "󰆍",
      },
      use_system_theming = false,  -- Use nvim theme instead of doughnut colors
    },
    concurrency = 4,
    go_cmd = { "go" },  -- Auto-detects goenv
    auto_install = {
      enabled = true,      -- Auto-install missing binaries on register
      silent = false,      -- Suppress install notifications
    },
    auto_check = {
      enabled = true,      -- Auto-check for updates (disabling also disables auto_update)
      frequency = "daily", -- "daily", "weekly", or hours (number)
    },
    auto_update = {
      enabled = false,     -- Auto-update when newer versions found (requires auto_check)
    },
  })
<

==============================================================================
7. HIGHLIGHTS                                              *glaze-highlights*

All highlight groups are prefixed with "Glaze". When `use_system_theming` is
false (default), a doughnut-themed pink/magenta colors are used.

  Group               Description ~
  GlazeH1             Main title
  GlazeH2             Section headers
  GlazeTitle          Window title
  GlazeBinary         Binary names
  GlazeUrl            Module URLs (italic)
  GlazePlugin         Plugin names
  GlazeDone           Success status
  GlazeError          Error status
  GlazeRunning        In-progress status
  GlazePending        Pending status
  GlazeProgressDone   Progress bar (filled)
  GlazeProgressTodo   Progress bar (empty)
  GlazeVersion        Version info
  GlazeTime           Timing info (italic)
  GlazeNormal         Normal text (links to NormalFloat)
  GlazeComment        Comments (links to Comment)
  GlazeDimmed         Dimmed text (links to Conceal)
  GlazeBorder         Window border
  GlazeButton         Inactive button (links to CursorLine)
  GlazeButtonActive   Active/selected button
  GlazeKey            Keybind hints
  GlazeIcon           Default icon color
  GlazeIconDone       Done icon
  GlazeIconError      Error icon
  GlazeIconRunning    Running/spinner icon
  GlazeBold           Bold text
  GlazeItalic         Italic text

==============================================================================
8. AUTO-UPDATE CHECKING                                    *glaze-auto-check*

Glaze can automatically check for newer versions of your registered binaries.

When enabled, Glaze checks on setup if enough time has passed since the last
check. It uses `go list -m -json <module>@latest` to find the latest version
and `go version -m <binary>` to determine the installed version.

State is stored in: `vim.fn.stdpath("data") .. "/glaze/state.json"`

Use `:GlazeCheck` to manually trigger a check at any time.

In the UI, binaries with available updates show a ⬆ indicator with version
info (e.g., "v1.0.0 → v1.1.0").

==============================================================================
9. FOR PLUGIN AUTHORS                                 *glaze-plugin-authors*

Register your binaries in your plugin's setup:
>lua
  local ok, glaze = pcall(require, "glaze")
  if ok then
    glaze.register("mytool", "github.com/me/mytool", {
      plugin = "myplugin.nvim",
      callback = function(success)
        if success then
          vim.notify("mytool updated!")
        end
      end,
    })
  end
<

You can still provide plugin-specific update commands:
>lua
  vim.api.nvim_create_user_command("MyPluginUpdate", function()
    require("glaze.runner").update({ "mytool" })
  end, {})
<

==============================================================================
vim:tw=78:ts=8:ft=help:norl: