headlights: Instructions file for Codex

AGENTS — Developer & AI-Agent Guide for headlights.nvim

This file is the canonical reference for anyone (human or AI) working on this codebase. Read it fully before making changes.

---

What this project is

headlights.nvim is a modern Neovim Lua rewrite of the original headlights.vim plugin.

It is a plugin browser: it discovers every loaded Neovim plugin and shows what each one contributes — commands, key mappings, abbreviations, functions, highlight groups, and source files — organised by plugin rather than as flat global lists.

Two display modes:

• Floating popup — hierarchical, interactive (Plugins → Categories → Items). Used automatically in GUI frontends (Neovide, nvui, …), or forced with :Headlights popup.
• Buffer display — formatted scratch buffer in a vsplit (headlights://plugins). Default in terminal Neovim, or forced with :Headlights buffer.

A CLI driver at bin/headlights runs the same pipeline headlessly and writes output to stdout. CI, the smoke test, and Docker all use it.

---

Repository layout

lua/headlights/
  init.lua        Public API: setup(), open()
  config.lua      Options with defaults (incl. extra_plugin_dirs)
  collector.lua   Live data snapshot from Neovim APIs
  bundler.lua     Groups scripts into bundles; attributes commands/maps via sid
  ui.lua          GUI detection + UI routing
  ui/
    popup.lua     Floating-window hierarchical menu
    buffer.lua    Scratch-buffer display (text / markdown / json)
  log.lua         Structured logging + performance timing
  health.lua      :checkhealth headlights

plugin/
  headlights.lua  Entry point: guards, version check, user commands

bin/
  headlights      Shell wrapper around `nvim -l bin/headlights.lua`
  headlights.lua  Headless entrypoint: collector → bundler → renderer → stdout

tests/
  minimal_init.lua            Bootstraps mini.test for headless test runs
  test_config.lua             Unit tests — config defaults & overrides
  test_collector.lua          Live-API tests for the collector
  test_bundler.lua            Pure-logic tests (incl. extra_plugin_dirs)
  test_ui_buffer.lua          Buffer renderer + open() tests
  test_ui_popup.lua           Popup build_menu_lines + open() tests
  test_integration.lua        Real-fixture before/after end-to-end tests
  fixtures/test_plugin.vim    Minimal fake plugin used by integration tests
  smoke/smoke.sh              Single end-to-end smoke test (bin/headlights)

docker/
  Dockerfile                  Ubuntu 24.04 + Neovim from the official tarball

scripts/
  session-start.sh            Print start-of-session status summary
  session-end.sh              Run quality gates + dump session summary
  docker-test.sh              Build image and run smoke (or any command)

doc/
  headlights-nvim.txt         Vim/Neovim help (`:help headlights`)

.github/workflows/
  ci.yml                      GitHub Actions — smoke + tests + lint