scripts/scaffold_plugin.py <plugin-name> --path <output-directory>

plugin-name/
├── lua/
│   └── plugin-name/
│       ├── init.lua        # Main entry point, setup() function
│       ├── config.lua      # Default configuration
│       ├── commands.lua    # User commands
│       ├── autocmds.lua    # Autocommands
│       └── utils.lua       # Helper functions
├── plugin/
│   └── plugin-name.lua     # Lazy-load trigger (optional)
├── doc/
│   └── plugin-name.txt     # Vimdoc help file
├── tests/
│   └── plugin_spec.lua     # Plenary tests
├── README.md
└── LICENSE

local M = {}

M.config = {
  -- Default options
}

function M.setup(opts)
  M.config = vim.tbl_deep_extend("force", M.config, opts or {})
  -- Initialize plugin
end

return M

{
  "author/plugin-name",
  dependencies = { "dependency/plugin" },
  event = "VeryLazy",           -- Lazy load on event
  ft = { "lua", "python" },     -- Lazy load on filetype
  cmd = { "Command" },          -- Lazy load on command
  keys = {                      -- Lazy load on keymap
    { "<leader>p", "<cmd>Command<cr>", desc = "Description" },
  },
  opts = {},                    -- Passed to setup()
  config = function(_, opts)    -- Custom config function
    require("plugin").setup(opts)
  end,
  init = function()             -- Runs at startup (before load)
    -- Set globals, options before plugin loads
  end,
  build = "make",               -- Build command after install
  enabled = true,               -- Conditionally enable
  cond = function()             -- Conditional loading
    return vim.fn.executable("node") == 1
  end,
  priority = 1000,              -- Load order (higher = earlier)
}

-- Buffer/window/cursor operations
local bufnr = vim.api.nvim_get_current_buf()
local winnr = vim.api.nvim_get_current_win()
local cursor = vim.api.nvim_win_get_cursor(0)  -- {row, col}, 1-indexed row

-- Get/set lines
local lines = vim.api.nvim_buf_get_lines(bufnr, 0, -1, false)
vim.api.nvim_buf_set_lines(bufnr, 0, -1, false, new_lines)

-- Create keymaps
vim.keymap.set("n", "<leader>x", function()
  -- action
end, { desc = "Description", buffer = bufnr })

-- Create user commands
vim.api.nvim_create_user_command("MyCommand", function(opts)
  -- opts.args, opts.bang, opts.range
end, { nargs = "*", bang = true, desc = "Description" })

-- Create autocommands
vim.api.nvim_create_autocmd({ "BufEnter", "BufWinEnter" }, {
  group = vim.api.nvim_create_augroup("MyGroup", { clear = true }),
  pattern = "*.lua",
  callback = function(ev)
    -- ev.buf, ev.file, ev.match
  end,
})

-- Notifications
vim.notify("Message", vim.log.levels.INFO)

-- Schedule for main loop (async safety)
vim.schedule(function()
  -- Safe to call API here
end)

-- Basic print (goes to :messages)
print(vim.inspect(value))

-- Notification (visible in UI)
vim.notify(vim.inspect(value), vim.log.levels.DEBUG)

-- Write to file
local f = io.open("/tmp/nvim-debug.log", "a")
f:write(vim.inspect(value) .. "\n")
f:close()

-- Recommended: nvim-dap with local-lua-debugger-vscode
{
  "mfussenegger/nvim-dap",
  dependencies = { "jbyuki/one-small-step-for-vimkind" },
  config = function()
    local dap = require("dap")
    dap.configurations.lua = {
      {
        type = "nlua",
        request = "attach",
        name = "Attach to running Neovim instance",
      },
    }
    dap.adapters.nlua = function(callback, config)
      callback({ type = "server", host = config.host or "127.0.0.1", port = config.port or 8086 })
    end
  end,
}

-- In lua/plugin-name/health.lua
local M = {}

function M.check()
  vim.health.start("plugin-name")

  if vim.fn.executable("dependency") == 1 then
    vim.health.ok("dependency found")
  else
    vim.health.error("dependency not found", { "Install with: brew install dependency" })
  end
end

return M

local M = {}

-- Private function
local function internal_helper()
end

-- Public API
function M.public_function()
  internal_helper()
end

return M

local MyClass = {}
MyClass.__index = MyClass

function MyClass.new(opts)
  local self = setmetatable({}, MyClass)
  self.value = opts.value or "default"
  return self
end

function MyClass:method()
  return self.value
end

return MyClass

-- Using vim.loop (libuv)
local uv = vim.loop

-- Timer
local timer = uv.new_timer()
timer:start(1000, 0, vim.schedule_wrap(function()
  -- Runs after 1 second
  timer:close()
end))

-- Async job
vim.fn.jobstart({ "command", "arg" }, {
  on_stdout = function(_, data)
    vim.schedule(function()
      -- Process output
    end)
  end,
  on_exit = function(_, code)
    vim.schedule(function()
      -- Handle completion
    end)
  end,
})

-- Using plenary.async (if available)
local async = require("plenary.async")
async.run(function()
  local result = async.wrap(function(callback)
    -- async operation
    callback(nil, "result")
  end, 1)()
end)

local ok, module = pcall(require, "module-name")
if not ok then
  vim.notify("module-name not found", vim.log.levels.WARN)
  return
end

-- tests/plugin_spec.lua
describe("plugin-name", function()
  local plugin = require("plugin-name")

  before_each(function()
    plugin.setup({})
  end)

  it("should have default config", function()
    assert.is_not_nil(plugin.config)
  end)

  it("should merge user config", function()
    plugin.setup({ option = "value" })
    assert.equals("value", plugin.config.option)
  end)
end)