Release 1.1.0: CI/CD rebuild, test suite, flavor detection fixes

.github/AGENTS.md

@@ -0,0 +1,53 @@
+# AGENTS
+
+## Project Scope
+
+PersonalPlayerNotes is a World of Warcraft addon written in Lua 5.1 with Ace3.
+
+- Read [README.md](../README.md) for the user-facing addon summary.
+- Treat [PersonalPlayerNotes.toc](../PersonalPlayerNotes.toc) as the authoritative load order and metadata manifest.
+- Main behavior lives in [PersonalPlayerNotes.lua](../PersonalPlayerNotes.lua), option definitions in [PersonalPlayerNotesConfig.lua](../PersonalPlayerNotesConfig.lua), and metadata/UI helpers in [PersonalPlayerNotesUtils.lua](../PersonalPlayerNotesUtils.lua).
+
+## Working Rules
+
+- Keep edits compatible with both Retail and Classic code paths unless the task is explicitly flavor-specific.
+- Prefer feature detection over hardcoded flavor checks (`WOW_PROJECT_ID`/`IsRetail`) for anything that depends on client API surface, e.g. `PersonalPlayerNotes:HasModernMenuAPI()`, `HasModernTooltipAPI()`, `HasModernSettingsAPI()`, `HasModernAddOnAPI()`, `HasModernUIReloadAPI()` in [PersonalPlayerNotesUtils.lua](../PersonalPlayerNotesUtils.lua). Classic clients have progressively picked up modern Retail APIs, so a flavor check can silently go stale.
+- When changing menu, tooltip, or player-interaction behavior, check both branches in [PersonalPlayerNotes.lua](../PersonalPlayerNotes.lua): the modern path uses `Menu.ModifyMenu` and `TooltipDataProcessor`; the legacy fallback path uses `UnitPopup_ShowMenu` hooks and `GameTooltip:HookScript`.
+- Some clients don't expose the `C_AddOns`/`C_UI` namespaces yet (confirmed live on Wrath Classic) — addon load/disable/reload for the legacy Shitlist migration must keep the `LoadAddOn`/`DisableAddOn`/`ReloadUI` fallback path guarded by `HasModernAddOnAPI()`/`HasModernUIReloadAPI()`.
+- Preserve the file order in [PersonalPlayerNotes.toc](../PersonalPlayerNotes.toc): embedded libs, locales, then Lua files. If a new file is added, place it deliberately.
+- Do not manually edit bundled libraries under `Libs/`. Dependency sourcing is controlled by [.pkgmeta](../.pkgmeta).
+- Do not replace the `.toc` version token `@project-version@`. Versioning is injected by the packager and read at runtime via `C_AddOns.GetAddOnMetadata()`.
+- Keep SavedVariables schema changes minimal and deliberate. Defaults are defined in [PersonalPlayerNotesConfig.lua](../PersonalPlayerNotesConfig.lua); profile or listed-player structure changes may require migration handling via `PersonalPlayerNotes:MigrateSavedVariablesSchema()` in [PersonalPlayerNotesUtils.lua](../PersonalPlayerNotesUtils.lua) and bumping `PersonalPlayerNotes.SCHEMA_VERSION`.
+- Preserve the legacy `Shitlist` migration path unless the task explicitly updates migration behavior.
+
+## Localization Rules
+
+- Localization strings use AceLocale with `L["PPN_..."]` keys.
+- When adding or renaming a localization key, update both [Locales/enUS.lua](../Locales/enUS.lua) and [Locales/zhCN.lua](../Locales/zhCN.lua) in the same change.
+- Reuse existing naming patterns for locale keys and option labels before adding new variants.
+
+## Validation
+
+- Format with [StyLua](https://github.com/JohnnyMorganz/StyLua) using [.stylua.toml](../.stylua.toml) (`make format` / `make format-check`). CI fails the `format` job if a file isn't formatted — don't hand-format against the grain of what StyLua would produce.
+- Preferred lint baseline is the existing luacheck configuration in [.luacheckrc](../.luacheckrc). Globals are declared explicitly (`globals`/`read_globals`), not blanket-ignored — if you introduce a genuinely new WoW API global, add it there rather than suppressing warning codes 111/112/113.
+- Match the repository editor assumptions in [.vscode/settings.json](../.vscode/settings.json): Lua 5.1, WoW API stubs, and a number of intentionally disabled diagnostics.
+- Pure Lua logic (no WoW API/Ace3 dependency) is unit tested with plain `lua5.1`, no WoW client required:
+  - [Tests/test_utils.lua](../Tests/test_utils.lua) - legacy Shitlist key parsing, client feature detection, addon metadata getters, SavedVariables schema migration, `OpenBlizzardOptions()` routing.
+  - [Tests/test_config.lua](../Tests/test_config.lua) - `PersonalPlayerNotesConfig.lua`'s AceDB defaults shape and all reasons/listed-players/alert CRUD accessors.
+  - [Tests/test_main.lua](../Tests/test_main.lua) - `PersonalPlayerNotes:GetOldConfigData()`'s legacy Shitlist data migration logic.
+  - [Tests/support/bootstrap.lua](../Tests/support/bootstrap.lua) - shared WoW/Ace3 stub loader used by the files above (not a test itself).
+  - Run all of them with `make test`, or individually with `lua5.1 Tests/test_X.lua`. Only add tests here for genuinely isolable logic (e.g. legacy data parsing, feature detection, CRUD accessors) - don't add artificial tests for WoW-API-coupled code that can't run outside a client (menu/tooltip rendering, AceGUI widgets, minimap icon).
+- [Tools/validate-toc.lua](../Tools/validate-toc.lua) (`make validate`) checks every `*.toc` file: required metadata fields, that `## Version` is still the `@project-version@` placeholder, plausible `## Interface*` values, that every referenced file exists, and no duplicate file entries.
+- CI behavior is defined in [.github/workflows/ci.yml](workflows/ci.yml) (format/lint/tests/validate/build, never publishes), [.github/workflows/release.yml](workflows/release.yml) (tag + publish, only on a merged PR to `master`), and [.github/workflows/interface-version.yml](workflows/interface-version.yml).
+
+## Packaging Notes
+
+- Packaging metadata lives in [.pkgmeta](../.pkgmeta); `.github/` and `.vscode/` are intentionally excluded from packaged releases.
+- The addon is packaged with BigWigsMods packager and publishes against CurseForge project `344967`.
+- Keep release-related documentation concise and prefer linking to existing files instead of duplicating workflow details here. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full release/testing process.
+
+## Useful Checks Before Editing
+
+- Search for an existing Ace3 option, chat command, or helper before adding a parallel implementation.
+- If a change touches metadata shown in the UI, confirm whether it should come from `.toc` via `GetAddOnMetadata()` rather than from a duplicated string.
+- If a change adds a new source file, update [PersonalPlayerNotes.toc](../PersonalPlayerNotes.toc) and verify any required locale or config wiring in the same edit.

.github/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing
+
+Notes for contributors and coding agents working on this repository. For the user-facing addon description, see [README.md](../README.md). For repository conventions (feature detection, TOC load order, localization/migration rules), see [AGENTS.md](AGENTS.md).
+
+## Development
+
+- Requires Lua 5.1 syntax/semantics (no runtime beyond the WoW client itself).
+- Embedded libraries (AceAddon-3.0, AceConfig-3.0, LibDataBroker-1.1, etc.) are **not** vendored in this repository — see [embeds.xml](../embeds.xml) and [.pkgmeta](../.pkgmeta). They're fetched automatically from their upstream repositories when the addon is packaged (see [Releases](#releases)). For a runnable local copy for manual in-game testing, run [Tools/Install-LocalAddon.ps1](../Tools/Install-LocalAddon.ps1) (PowerShell) — it links a WoW AddOns folder to this checkout (so changes are picked up on `/reload`) and fetches the libraries listed in `.pkgmeta` into `Libs/`. It only needs `git` (no separate SVN client is installed or required; the SVN-hosted externals are fetched with `git svn`, which ships with Git for Windows). Run `.\Tools\Install-LocalAddon.ps1 -Uninstall` to remove the link again. Alternatively, run the [BigWigsMods packager](https://github.com/BigWigsMods/packager) locally to build an actual zip instead of a live link.
+
+## Running checks and tests
+
+[![CI](https://github.com/Limmek/PersonalPlayerNotes/actions/workflows/ci.yml/badge.svg)](https://github.com/Limmek/PersonalPlayerNotes/actions/workflows/ci.yml)
+
+All checks below run in [workflows/ci.yml](workflows/ci.yml) on every push and pull request, and never publish anything. A `Makefile` wraps the same commands locally:
+
+| Command              | What it does                                                            |
+|----------------------|--------------------------------------------------------------------------|
+| `make format`        | Formats all Lua files in-place with [StyLua](https://github.com/JohnnyMorganz/StyLua) (config: [.stylua.toml](../.stylua.toml)) |
+| `make format-check`   | Checks formatting without writing changes (same check CI runs)          |
+| `make lint`           | Runs [luacheck](https://github.com/mpeterv/luacheck) using [.luacheckrc](../.luacheckrc) |
+| `make test`           | Runs the pure-Lua unit tests (no WoW client required) with Lua 5.1      |
+| `make validate`       | Runs [Tools/validate-toc.lua](../Tools/validate-toc.lua): checks required TOC metadata, that every referenced file exists, no duplicate file entries, and that `## Version` is still the packager placeholder |
+| `make build`          | Builds a local, unsigned addon zip with the BigWigsMods packager (no upload) |
+| `make check`          | Runs `format-check`, `lint`, `test`, and `validate` together             |
+
+Equivalent raw commands (if you don't have `make`, e.g. on plain Windows without Git Bash/WSL):
+```sh
+stylua --check .          # or without --check to write
+luacheck .
+lua5.1 Tests/test_utils.lua
+lua5.1 Tests/test_config.lua
+lua5.1 Tests/test_main.lua
+lua5.1 Tools/validate-toc.lua
+```
+
+## Releases
+
+[![Interface versions](https://github.com/Limmek/PersonalPlayerNotes/actions/workflows/interface-version.yml/badge.svg)](https://github.com/Limmek/PersonalPlayerNotes/actions/workflows/interface-version.yml)
+[![Release](https://github.com/Limmek/PersonalPlayerNotes/actions/workflows/release.yml/badge.svg)](https://github.com/Limmek/PersonalPlayerNotes/actions/workflows/release.yml)
+
+Releases are fully automated via [workflows/release.yml](workflows/release.yml), and only happen on pull requests merged into `master` (or manual dispatch) — never on every push:
+
+1. The `tag` job runs [K-Phoen/semver-release-action](https://github.com/K-Phoen/semver-release-action) (pinned to `v1.3.2`), which decides whether the merged PR warrants a new semver tag (based on the PR's labels — see that action's docs) and creates the git tag + GitHub release if so. If no new tag is warranted, nothing else in this workflow runs.
+2. The `package` job (gated on step 1 actually producing a tag) runs the [BigWigsMods packager](https://github.com/BigWigsMods/packager) (pinned to the exact release `v2.5.1`, not a floating tag) to build a clean release zip (excluding dev-only files per [.pkgmeta](../.pkgmeta)), using the git tag as the addon version (the `.toc`'s `@project-version@` placeholder — see [.luacheckrc](../.luacheckrc)/AGENTS.md — is substituted in at this point), and publishes it to GitHub Releases and CurseForge (project `344967`).
+3. Credentials (`CF_API_KEY`, `GITHUB_OAUTH`) are supplied via repository secrets, never hardcoded. These names are what packager `v2.5.1` actually reads (verified from its source) — a future packager upgrade past its unreleased "Normalize api token env vars" change would need `CF_API_TOKEN`/`GITHUB_API_TOKEN` instead.
+4. A merge only reaches the `release` workflow's intended effect (an actual publish) if [workflows/ci.yml](workflows/ci.yml) passed first — this repository's branch protection rules on `master` should require the `ci.yml` jobs (`format`, `luacheck`, `tests`, `validate`, `build`) as required status checks, since a workflow file alone cannot enforce that.
+
+[workflows/interface-version.yml](workflows/interface-version.yml) separately keeps the declared `## Interface` versions in [PersonalPlayerNotes.toc](../PersonalPlayerNotes.toc) up to date on a daily schedule.
+
+## Project structure
+
+- [PersonalPlayerNotes.toc](../PersonalPlayerNotes.toc) — addon manifest and load order.
+- [PersonalPlayerNotes.lua](../PersonalPlayerNotes.lua) — initialization, menu/tooltip hookups, legacy Shitlist migration.
+- [PersonalPlayerNotesConfig.lua](../PersonalPlayerNotesConfig.lua) — AceDB defaults and AceConfig options tables.
+- [PersonalPlayerNotesUtils.lua](../PersonalPlayerNotesUtils.lua) — metadata getters, feature detection, SavedVariables migration, GUI helpers.
+- [Locales/](../Locales/) — AceLocale string tables (`enUS.lua`, `zhCN.lua`).
+- [Tests/](../Tests/) — pure-Lua unit tests runnable outside of WoW.
+- [Tools/](../Tools/) — local dev tooling, e.g. [Install-LocalAddon.ps1](../Tools/Install-LocalAddon.ps1) for setting up a runnable local checkout.
+- [Tools/validate-toc.lua](../Tools/validate-toc.lua) — pure-Lua TOC/addon-structure validator, used by both CI and `make validate`.
+- [embeds.xml](../embeds.xml) / [.pkgmeta](../.pkgmeta) — embedded Ace3 library declarations and packaging config.
+- [.stylua.toml](../.stylua.toml) — StyLua formatting config.
+- [Makefile](../Makefile) — local developer commands (`format`, `format-check`, `lint`, `test`, `validate`, `build`, `check`).
+- [changelog.txt](../changelog.txt) — release changelog consumed by the packager.
+- [AGENTS.md](AGENTS.md) — repo-specific conventions for contributors and coding agents.

.github/workflows/ci.yml

@@ -0,0 +1,101 @@
+name: CI
+
+# Runs on every push and pull request. Never publishes or uploads anywhere -
+# see release.yml for the publish pipeline. This workflow is what branch
+# protection should require to pass before merging to master.
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - master
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  format:
+    name: Format check (StyLua)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone project
+        uses: actions/checkout@v4
+
+      - name: Check formatting
+        uses: JohnnyMorganz/stylua-action@v5
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          version: "2.5.2"
+          args: --check .
+
+  luacheck:
+    name: Luacheck
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone project
+        uses: actions/checkout@v4
+
+      - name: Install and run Luacheck
+        uses: nebularg/actions-luacheck@v1
+        with:
+          args: "--no-color -q"
+
+  tests:
+    name: Lua unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone project
+        uses: actions/checkout@v4
+
+      - name: Install Lua 5.1
+        run: sudo apt-get update && sudo apt-get install -y lua5.1
+
+      - name: Run unit tests
+        run: |
+          set -e
+          for f in Tests/test_utils.lua Tests/test_config.lua Tests/test_main.lua; do
+            echo "-- $f --"
+            lua5.1 "$f"
+          done
+
+  validate:
+    name: Validate addon (TOC, file structure)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone project
+        uses: actions/checkout@v4
+
+      - name: Install Lua 5.1
+        run: sudo apt-get update && sudo apt-get install -y lua5.1
+
+      - name: Validate .toc files
+        run: lua5.1 Tools/validate-toc.lua
+
+  build:
+    name: Build package (no upload)
+    needs: [format, luacheck, tests, validate]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone project
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # -d skips all uploading (CurseForge/WoWInterface/Wago/GitHub) - this
+      # only proves the package builds. -p 0 unsets the CurseForge project id
+      # for this dry run so it doesn't attempt any CurseForge API calls
+      # (which would need CF_API_KEY, not available to PRs from forks).
+      - name: Build package artifact
+        uses: BigWigsMods/packager@v2.5.1
+        with:
+          args: -d -p 0 -w 0 -a 0 -m .pkgmeta
+
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: PersonalPlayerNotes-build-${{ github.sha }}
+          path: .release/*.zip
+          retention-days: 14
+          if-no-files-found: error

.github/workflows/interface-version.yml

@@ -2,15 +2,8 @@ name: Update TOC Interface version(s)
 
 on:
   workflow_dispatch:
-  # push:
-  #   branches:
-  #     - master
-  # workflow_run:
-  #     workflows: ['Luacheck']
-  #     types:
-  #       - completed
-  # schedule:
-  #   - cron: 0 12 * * *
+  schedule:
+    - cron: 0 12 * * *
 
 jobs:
   run:
@@ -24,25 +17,21 @@ jobs:
         uses: p3lim/toc-interface-updater@v4
         with:
           flavor: vanilla
-          future: true
 
       - name: Checking Wrath
         uses: p3lim/toc-interface-updater@v4
         with:
           flavor: wrath
-          future: true
 
-      - name: Checking Cata
+      - name: Checking Mists
         uses: p3lim/toc-interface-updater@v4
         with:
-          flavor: cata
-          future: true
+          flavor: mists
 
       - name: Checking Retail
         uses: p3lim/toc-interface-updater@v4
         with:
           flavor: retail
-          future: true
 
       - name: Commit changes
         uses: EndBug/add-and-commit@v10