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

Author:   Tai Groot <tai@taigrr.com>
License:  MIT
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

                                                       *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 = "󰆍",
      },
    },
    concurrency = 4,
    go_cmd = { "go" },  -- Auto-detects goenv
    auto_check = {
      enabled = true,      -- Auto-check for updates on setup
      frequency = "daily", -- "daily", "weekly", or hours (number)
    },
  })
<

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

All highlight groups are prefixed with "Glaze":

  GlazeH1             Main title
  GlazeH2             Section headers
  GlazeBinary         Binary names
  GlazeUrl            Module URLs
  GlazePlugin         Plugin names
  GlazeDone           Success status
  GlazeError          Error status
  GlazeRunning        In-progress status
  GlazeProgressDone   Progress bar (filled)
  GlazeProgressTodo   Progress bar (empty)
  GlazeVersion        Version info
  GlazeTime           Timing info

==============================================================================
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: