Modernize build, fix mapping listing, persistence and edit bug

[marlon-sousa]

Summary

Completes the in-progress work to list all NVDA app modules, and modernizes the build/tooling to match the sibling EnhancedDictionaries add-on.

Code fixes

• List every available app module by enumerating the appModules package, not just the ~40 aliases in EXECUTABLE_NAMES_TO_APP_MODS. This also picks up modules provided by other add-ons.
• Reinstall-safe persistence: mappings now live in NVDA's user config dir (globalVars.appArgs.configPath) instead of the add-on folder (which is wiped on update/reinstall). Files from 0.2.0 are migrated automatically on load.
• Fix add/modify detection in the mapping dialog (it compared the app name against the list of available modules), and preserve the true original module across edits so Remove restores the correct module.
• Documented the notAssociated neutral module; removed dead code and stray a.txt.

Build / tooling (ported from EnhancedDictionaries)

• Typed scons NVDATool builders, cleaner gettexttool, new sconstruct, typed buildVars.py (with changelog), manifest.ini.tpl + manifest-translated.ini.tpl, flake8.ini and .pre-commit-config.yaml updates.
• CI replaced with a reusable validate.yml plus pr-checks.yml and release.yml (branch main, MIT license). Releases publish the .nvda-addon to GitHub Releases; datastore submission is manual.

Version

Bumped to 0.3.0; lastTestedNVDAVersion = 2026.1.0 (minimum kept at 2024.1 — the APIs used exist since ~2023.1). Changelog is in buildVars.py addon_changelog and rendered into manifest.ini.

Verified locally (build)

• scons builds CustomAppModulesMapper-0.3.0.nvda-addon with correct contents
• scons pot generates the translation template
• pre-commit run --all-files passes (ast / case-conflict / yaml / flake8)

---

Functional test script

Run against NVDA 2026.1 with the packaged CustomAppModulesMapper-0.3.0.nvda-addon. The config file referenced below is customModulesMapping.pickle in the NVDA user config dir (installed: %APPDATA%\nvda\; portable: <portable>\userConfig\).

0. Install

1. Build: scons.
2. Install the generated .nvda-addon and restart NVDA when prompted.

• NVDA log shows addon loaded and (first run) Custom mappings created.

1. Full module list is available (the core fix)

1. NVDA menu → Preferences → Settings → Custom Application Module Mapper.
2. Press Add mapping and open the App module combo box.

• The combo lists many modules matched by name (e.g. notepad, winword, soffice, firefox, thunderbird), not just alias targets like eclipse/code.
• notAssociated is present; nvda, javaw, msedgewebview2 and the touch-keyboard host are absent.

2. Add a mapping and apply

1. In the Add dialog set App = dbeaver (or any installed app you can launch), App module = notepad, OK, then OK on Settings.

• The mapping shows in the list.

2. Launch the target app, focus it, open the Python console (NVDA+Ctrl+Z) and run:
   import api; print(type(api.getFocusObject().appModule).__module__)

• It reports the mapped module (appModules.notepad).

3. Persistence across NVDA restart

1. Restart NVDA.

• customModulesMapping.pickle exists in the config dir (not in the add-on folder).
• Log shows Custom mappings loaded from file and Associating dbeaver app with notepad module; the mapping still shows in Settings and is still applied.

4. Reinstall-safe (the reason for the config-dir move)

1. Uninstall the add-on, restart, reinstall 0.3.0, restart.

• The dbeaver → notepad mapping is still present and applied (the pickle survived because it lives in the config dir).

5. Migration from 0.2.0

1. With the add-on removed, place an old-style pickle at <addon folder>\customModulesMapping.pickle (or install 0.2.0, add a mapping, then upgrade in place to 0.3.0).
2. Restart NVDA.

• Log shows Migrated custom mappings to the NVDA configuration directory; the file now exists in the config dir and no longer in the add-on folder; the mapping still works.

6. Modify preserves the original, Remove restores it

1. Add dbeaver → eclipse (NVDA's real default for dbeaver).
2. Edit it (Add again with the same app) to dbeaver → notepad. Save.

• Mapping now resolves to notepad.

3. Select the mapping, Remove mapping, Save.

• dbeaver resolves to eclipse again (the true original), not to notepad.

7. Disassociate via notAssociated

1. Map an app that has its own module (e.g. notepad → notAssociated). Save, relaunch the app.

• Focus reports appModules.notAssociated, i.e. no app-specific behavior.

8. Secure mode

1. Start NVDA on a secure screen (e.g. lock screen / UAC) with the add-on installed.

• No errors; the settings panel is absent and mappings are not loaded (guarded by globalVars.appArgs.secure).

🤖 Generated with Claude Code

[github-actions]

Packaged add-on artifact

• Commit: 5cbc1ec (5cbc1ec)
• Artifact: https://github.com/marlon-sousa/CustomAppModulesMapper/actions/runs/29285044176/artifacts/8292817904
• Run: https://github.com/marlon-sousa/CustomAppModulesMapper/actions/runs/29285044176

[github-actions]

Packaged add-on artifact

• Commit: 0a82a4a (0a82a4a)
• Artifact: https://github.com/marlon-sousa/CustomAppModulesMapper/actions/runs/29286191125/artifacts/8293248321
• Run: https://github.com/marlon-sousa/CustomAppModulesMapper/actions/runs/29286191125