qplotter 1.6.0b3__tar.gz

qplotter-1.6.0b3/Agents.md

@@ -0,0 +1,110 @@
+# Project instructions for Codex
+
+## Scope
+
+The program is required only to show data generated by QCoDeS. This means for example that only the most recend .db specification needs to be supported.
+
+## Database access invariant
+
+qPlot must never write, truncate, replace, rename, or delete an existing QCoDeS main database, its `-wal` file, or its rollback `-journal`. Ordinary viewing must not checkpoint the database, change journal mode, migrate its schema, or otherwise cause database content to be written.
+
+For trusted live viewing of a local WAL-mode database, qPlot's pinned SQLite reader may create, open, resize, memory-map, lock, and modify only the exact regular, colocated `<database>-shm` file through SQLite's standard WAL shared-memory operations. Resulting SHM content and timestamp changes are permitted. qPlot must not rename or delete the SHM file, and no application code may write it outside the pinned SQLite VFS.
+
+All main-database and WAL handles used by qPlot must remain physically read-only. Reader transactions must be short, bounded, and cancellable so that viewing does not indefinitely delay QCoDeS checkpoints.
+
+The sole additional exception is explicit synthetic test-database generation. That workflow may create temporary files and create or atomically replace only the exact output path selected by the user. Replacing an existing file requires explicit user confirmation.
+
+For trusted live reading, the selected local database directory and its path components are assumed trusted and are not expected to be concurrently redirected by a hostile actor. qPlot need not resist adversarial namespace substitution. SQLite’s standard handling of the exact -shm, including permission-mode normalization such as POSIX fchmod, is permitted. Trusted live reading must run unprivileged.
+
+## Settings compatibility
+
+Backward compatibility with older qPlot settings formats is not required. The small user base does not justify additional compatibility complexity.
+
+Do not add settings migrations or support for legacy settings formats unless explicitly requested. When the settings schema changes, resetting incompatible settings to current defaults is acceptable; the application
+should still start normally.
+
+Continue validating current settings and saving them safely. This policy applies only to qPlot settings and does not relax the database-access invariant or measurement-data correctness requirements.
+
+## Python environment
+
+Always use the project virtual environment for Python commands. If the
+environment is activated, use `python -m ...`; otherwise call the environment's
+Python executable directly.
+
+On Windows:
+- Prefer `.venv\Scripts\python.exe` if the environment lives inside the
+  repository.
+- In local checkouts where the environment is next to the repository, use
+  `..\.venv\Scripts\python.exe`.
+- Use the selected venv Python with `-m pytest` instead of bare `pytest`.
+- Use the selected venv Python with `-m pip` instead of bare `pip`.
+
+On macOS/Linux:
+- Use `.venv-mac/bin/python` if the environment is not already activated.
+- Use the selected venv Python with `-m pytest` instead of bare `pytest`.
+- Use the selected venv Python with `-m pip` instead of bare `pip`.
+
+Do not try the system Python first.
+Do not run tests with bare `pytest`; run them through the appropriate venv Python for the current OS.
+
+## Test commands
+
+Use these commands when relevant:
+
+Windows:
+```powershell
+python -m pytest
+```
+
+macOS/Linux:
+```bash
+python -m pytest
+```
+## After code changes
+
+If you modify application code, before the final response:
+
+1. Run the relevant automated tests.
+2. If the change affects runtime behavior or UI, start qPlot from the project venv.
+
+On Windows, prefer:
+
+```powershell
+..\.venv\Scripts\python.exe -m qplot
+```
+
+On macOS/Linux, prefer:
+
+```bash
+.venv-mac/bin/python -m qplot
+```
+
+## Matplotlib cache
+
+On macOS, prefix every Python command that may import Matplotlib with the same
+writable cache directory:
+
+```bash
+MPLCONFIGDIR=/private/tmp/qplot-matplotlib-cache .venv-mac/bin/python -m pytest
+```
+
+Reuse this exact cache directory; do not create a fresh temporary directory for
+each run. The first invocation may build the font cache once, but subsequent
+runs should reuse it. Set `MPLCONFIGDIR` on each command invocation because
+separate Codex shell commands may not share exported environment variables.
+
+For automated qPlot startup smoke checks, use:
+
+```bash
+QT_QPA_PLATFORM=offscreen MPLCONFIGDIR=/private/tmp/qplot-matplotlib-cache .venv-mac/bin/python -m qplot
+```
+
+Omit `QT_QPA_PLATFORM=offscreen` when a visible manual UI check is required.
+
+## GitHub publishing
+
+Do not use the GitHub CLI (`gh`) or require `gh auth` for repository work.
+
+Use the configured Git remote and credentials for `git fetch`, `git push`, and tag pushes. Use the connected GitHub app for pull-request operations.
+
+If GitHub release creation is needed but unavailable through the connected app, stop and ask for direction; do not fall back to `gh`.