From 6b38697d7f20652da04102de69f8a6873a8e26c6 Mon Sep 17 00:00:00 2001
From: Giovanni Harting <539@idlegandalf.com>
Date: Sat, 8 Nov 2025 22:34:59 +0100
Subject: [PATCH] chore: add repo tooling

---
 .luacheckrc | 16 ++++++++++++++++
 AGENTS.md   | 22 ++++++++++++++++++++++
 justfile    | 10 ++++++++++
 stylua.toml |  6 ++++++
 4 files changed, 54 insertions(+)
 create mode 100644 .luacheckrc
 create mode 100644 AGENTS.md
 create mode 100644 justfile
 create mode 100644 stylua.toml

diff --git a/.luacheckrc b/.luacheckrc
new file mode 100644
index 0000000..8a044fd
--- /dev/null
+++ b/.luacheckrc
@@ -0,0 +1,16 @@
+std = "lua52"
+unused_args = false
+max_line_length = 120
+
+read_globals = {
+    "mp",
+    "mpv",
+}
+
+allow_defined_top = true
+
+files["**/*.lua"] = {
+    ignore = {
+        "631", -- allow string.format mismatch warnings common in mpv scripts
+    },
+}
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..8992605
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,22 @@
+# AGENTS
+
+## Repository Purpose
+- Provide a single home for personal mpv Lua scripts so they share release tooling, lint rules, and documentation.
+- Keep each script self-documenting through richly annotated headers while this file explains meta-level conventions.
+
+## Layout & Conventions
+- `scripts/` — every Lua script lives here; filenames stay unique and map 1:1 to `script-name` values.
+- `scripts/<name>.lua` — script headers must summarize behavior, configuration, and dependencies because per-script AGENTS docs were removed.
+- Root configs (`.luacheckrc`, `stylua.toml`) apply to the entire tree; do not duplicate them inside subdirectories.
+- Tests, fixtures, or helper assets should be placed alongside the script that depends on them using clear suffixes (e.g., `*_spec.lua`).
+
+## Tooling
+- **Linting**: `luacheck scripts` (Lua 5.2 std, mp/mpv globals allowed, long format warnings suppressed via config).
+- **Formatting**: `stylua scripts` (2-space indent, 100-column width, Unix newlines, double quotes preferred).
+- **mpv runtime**: target mpv 0.36+ with the bundled Lua 5.2 interpreter; scripts should avoid third-party Lua modules unless vendored.
+- **Automation**: use `just` targets for common chores—`just fmt` formats, `just fmt-check` verifies formatting, `just lint` runs luacheck, and `just check` chains the formatting check plus lint.
+
+## Working With The Repo
+1. Add new scripts under `scripts/` and document behavior in the top comment block.
+2. Run `stylua` followed by `luacheck` before committing.
+3. Update this file when repo-level layout or tooling changes so future contributors understand the structure.
diff --git a/justfile b/justfile
new file mode 100644
index 0000000..18bd10b
--- /dev/null
+++ b/justfile
@@ -0,0 +1,10 @@
+lint:
+	luacheck scripts
+
+fmt:
+	stylua scripts
+
+fmt-check:
+	stylua --check scripts
+
+check: fmt-check lint
diff --git a/stylua.toml b/stylua.toml
new file mode 100644
index 0000000..9508a89
--- /dev/null
+++ b/stylua.toml
@@ -0,0 +1,6 @@
+column_width = 100
+indent_type = "Spaces"
+indent_width = 2
+line_endings = "Unix"
+quote_style = "AutoPreferDouble"
+call_parentheses = "Always"