From 7baac306ed86bc2071fc6a3a5e6d4f94cd7fb817 Mon Sep 17 00:00:00 2001 From: Reimar Bauer Date: Wed, 27 May 2026 10:43:51 +0200 Subject: [PATCH 1/2] init for claudecode and opencode --- AGENTS.md | 19 +++++++++++++++++++ CLAUDE.md | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..347eb3572 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,19 @@ +# AGENTS.md + +## Environment & Toolchain +- **Runtime**: Python < 3.12. +- **Env Manager**: Pixi. Use `pixi shell -e dev` for development. +- **Verification Flow**: `flake8 mslib/` -> `codespell` -> `pytest`. + +## Architecture Notes +- **Structure**: Single package `mslib` containing multiple applications. +- **Entrypoints**: Defined in `pyproject.toml` (scripts: `mss`, `mscolab`, `msidp`, `mswms`, `mssautoplot`). +- **Components**: + - `msui`: PyQt GUI. + - `mscolab`/`mswms`/`msidp`: Flask-based services. + +## Constraints & Quirks +- **GUI Tests**: Uses `pytest-qt`. +- **Database**: `mscolab` uses `flask-migrate` for schema management. +- **OS Dependencies**: Some dependencies (e.g., `dbus-python`, `libxmlsec1`) are platform-specific in `pixi.toml`. +- **Documentation**: Refer to `CLAUDE.md` for exact developer commands. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..70554aec1 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,37 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Development Commands + +### Environment Setup +- Enter development environment: `pixi shell -e dev` +- Install dependencies: `pixi install` + +### Testing +- Run all tests: `pixi run -e dev env QT_QPA_PLATFORM=offscreen pytest -n logical tests` +- Run a specific test file: `pixi run -e dev env QT_QPA_PLATFORM=offscreen pytest tests/test_file.py` +- Run a specific test function: `pixi run -e dev env QT_QPA_PLATFORM=offscreen pytest tests/test_file.py::test_function` + +### Linting & Quality +- Lint code: `pixi run -e dev flake8 mslib/ tests/` +- Check spelling: `pixi run -e dev codespell` + +## Architecture Overview + +The Mission Support System (MSS) is a Python-based suite for planning atmospheric research flights. The codebase is organized as a single package `mslib` containing several distinct applications and shared utilities. + +### Core Components (`mslib/`) +- **`msui/`**: The primary GUI application built with PyQt. +- **`mscolab/`**: Collaboration server using Flask and Flask-SocketIO for flight planning. +- **`mswms/`**: Web Map Service System using Flask, providing server-side functionality. +- **`msidp/`**: Identity Provider service for authentication (SAML). +- **`utils/`**: Shared utility functions, including `mssautoplot` for automated plotting. +- **`support/`**: Support modules used across the different applications. +- **`plugins/`**: Extensibility points for adding new functionality. + +### Key Technologies +- **GUI**: PyQt +- **Web**: Flask, SQLAlchemy, Flask-SocketIO +- **Scientific Stack**: NumPy, SciPy, Matplotlib, NetCDF4, MetPy, Skyfield +- **Package Management**: Pixi (conda-forge) From 9d8baac7a5f265149e1b41a16bcbaaafcfab995d Mon Sep 17 00:00:00 2001 From: Reimar Bauer Date: Wed, 27 May 2026 10:57:42 +0200 Subject: [PATCH 2/2] update --- AGENTS.md | 75 ++++++++++++++++++++++++++++++++------------ CLAUDE.md | 93 +++++++++++++++++++++++++++++++++++-------------------- 2 files changed, 116 insertions(+), 52 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 347eb3572..fcb42f5e9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,19 +1,56 @@ -# AGENTS.md - -## Environment & Toolchain -- **Runtime**: Python < 3.12. -- **Env Manager**: Pixi. Use `pixi shell -e dev` for development. -- **Verification Flow**: `flake8 mslib/` -> `codespell` -> `pytest`. - -## Architecture Notes -- **Structure**: Single package `mslib` containing multiple applications. -- **Entrypoints**: Defined in `pyproject.toml` (scripts: `mss`, `mscolab`, `msidp`, `mswms`, `mssautoplot`). -- **Components**: - - `msui`: PyQt GUI. - - `mscolab`/`mswms`/`msidp`: Flask-based services. - -## Constraints & Quirks -- **GUI Tests**: Uses `pytest-qt`. -- **Database**: `mscolab` uses `flask-migrate` for schema management. -- **OS Dependencies**: Some dependencies (e.g., `dbus-python`, `libxmlsec1`) are platform-specific in `pixi.toml`. -- **Documentation**: Refer to `CLAUDE.md` for exact developer commands. +# MSS (Mission Support System) + +## Setup + +``` +pixi shell # activate dev environment (dev + docs features) +``` + +Python constraint: **< 3.12** (pinned in pixi.toml). + +## Commands + +``` +# lint +pixi run -e dev flake8 +git ls-files -z | xargs -0 pixi run -e dev codespell --check-filenames + +# test (full suite) +pixi run -e dev env QT_QPA_PLATFORM=offscreen pytest -v -n logical --durations=20 --cov=mslib tests + +# run a single test file +pixi run -e dev env QT_QPA_PLATFORM=offscreen pytest tests/test_something.py -v + +# headless Qt (CI default, required on macOS) +QT_QPA_PLATFORM=offscreen pixi run -e dev -n logical pytest tests/ + +# coverage XML +pixi run -e dev coverage xml +``` + +## Architecture + +Single package `mslib` with four main subpackages: + +- **msui** — PyQt5 desktop GUI (`msui` entrypoint). Main window: `mslib.msui.msui_mainwindow`. +- **mscolab** — Flask collaborative server (`mscolab` entrypoint). Server: `mslib.mscolab.server`. DB models: `mslib.mscolab.models`. +- **mswms** — WMS geospatial service (`mswms` entrypoint). Driver: `mslib.mswms.mss_plot_driver`. +- **utils** — Shared utilities (config, auth, coordinate handling, netCDF tools). + +CLI entrypoints (pixi env): `msui`, `mscolab`, `mswms`, `msidp`, `mssautoplot`, `mss`. + +## Testing notes + +- `conftest.py` auto-generates test config dirs in a temp directory and loads `mswms_settings` / `mscolab_settings` modules dynamically. Tests read from `tests.constants`. +- `tests/fixtures.py` provides session-scoped `mscolab_server`, `mswms_server`, `mscolab_app`, `mscolab_managers` fixtures plus Qt helpers (`qtbot`, `fail_if_open_message_boxes_left`). +- Qt tests require `QT_QPA_PLATFORM=offscreen` on headless machines. +- Keyring is mocked via `TestKeyring` in conftest — no real keyring needed. +- Tests clean config state after every test via `reset_config` autouse fixture. +- MSColab tests spin up a real Flask-SocketIO subprocess on a random port. + +## Conventions + +- Flake8: max-line-length 120. Ignored: E124,E125,E402,W503,W504,A005. Excluded dirs: `mslib/msui/qt5/`, `mslib/mscolab/migrations/`. +- Codespell: exceptions in `codespell-ignored-lines.txt`. Ignore list: PRES, degreeE, doubleClick, indexIn, socio-economic, EMAC, emac. +- Qt UI files (`qt5/ui_*.py`) are generated from `.ui` — do not edit by hand. +- No CRLF in git. Whitespace at EOL in `tests/data/example.txt` and `docs/samples/flight-tracks/example.txt` is intentional. diff --git a/CLAUDE.md b/CLAUDE.md index 70554aec1..be4dbd182 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,36 +2,63 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. -## Development Commands - -### Environment Setup -- Enter development environment: `pixi shell -e dev` -- Install dependencies: `pixi install` - -### Testing -- Run all tests: `pixi run -e dev env QT_QPA_PLATFORM=offscreen pytest -n logical tests` -- Run a specific test file: `pixi run -e dev env QT_QPA_PLATFORM=offscreen pytest tests/test_file.py` -- Run a specific test function: `pixi run -e dev env QT_QPA_PLATFORM=offscreen pytest tests/test_file.py::test_function` - -### Linting & Quality -- Lint code: `pixi run -e dev flake8 mslib/ tests/` -- Check spelling: `pixi run -e dev codespell` - -## Architecture Overview - -The Mission Support System (MSS) is a Python-based suite for planning atmospheric research flights. The codebase is organized as a single package `mslib` containing several distinct applications and shared utilities. - -### Core Components (`mslib/`) -- **`msui/`**: The primary GUI application built with PyQt. -- **`mscolab/`**: Collaboration server using Flask and Flask-SocketIO for flight planning. -- **`mswms/`**: Web Map Service System using Flask, providing server-side functionality. -- **`msidp/`**: Identity Provider service for authentication (SAML). -- **`utils/`**: Shared utility functions, including `mssautoplot` for automated plotting. -- **`support/`**: Support modules used across the different applications. -- **`plugins/`**: Extensibility points for adding new functionality. - -### Key Technologies -- **GUI**: PyQt -- **Web**: Flask, SQLAlchemy, Flask-SocketIO -- **Scientific Stack**: NumPy, SciPy, Matplotlib, NetCDF4, MetPy, Skyfield -- **Package Management**: Pixi (conda-forge) +## Setup + +``` +pixi shell -e dev # activate dev environment (dev + docs features) +``` + +Python constraint: **< 3.12** (pinned in pixi.toml). + +## Commands + +```bash +# lint +pixi run -e dev flake8 +git ls-files -z | xargs -0 pixi run -e dev codespell --check-filenames + +# test (full suite) +pixi run -e dev env QT_QPA_PLATFORM=offscreen pytest -v -n logical --durations=20 --cov=mslib tests + +# run a single test file +pixi run -e dev env QT_QPA_PLATFORM=offscreen pytest tests/test_something.py -v + +# headless Qt (CI default, required on macOS) +QT_QPA_PLATFORM=offscreen pixi run -e dev -n logical pytest tests/ + +# coverage XML +pixi run -e dev coverage xml + +# repeat tests +pixi run -e dev env QT_QPA_PLATFORM=offscreen pytest --count=10 + +``` + +## Architecture + +Single package `mslib` with four main subpackages: + +- **msui** — PyQt5 desktop GUI (`msui` entrypoint). Main window: `mslib.msui.msui_mainwindow`. +- **mscolab** — Flask collaborative server (`mscolab` entrypoint). Server: `mslib.mscolab.server`. DB models: `mslib.mscolab.models`. +- **mswms** — WMS geospatial service (`mswms` entrypoint). Driver: `mslib.mswms.mss_plot_driver`. +- **utils** — Shared utilities (config, auth, coordinate handling, netCDF tools). + +CLI entrypoints (pixi env): `msui`, `mscolab`, `mswms`, `msidp`, `mssautoplot`, `mss`. + +Tests mirror the package structure under `tests/` with subdirectories `_test_mscolab/`, `_test_msui/`, `_test_mswms/`, `_test_plugins/`, `_test_utils/`. + +## Testing notes + +- `conftest.py` auto-generates test config dirs in a temp directory and loads `mswms_settings` / `mscolab_settings` modules dynamically. Tests read from `tests.constants`. +- `tests/fixtures.py` provides session-scoped `mscolab_server`, `mswms_server`, `mscolab_app`, `mscolab_managers` fixtures plus Qt helpers (`qtbot`, `fail_if_open_message_boxes_left`). +- Qt tests require `QT_QPA_PLATFORM=offscreen` on headless machines. +- Keyring is mocked via `TestKeyring` in conftest — no real keyring needed. +- Tests clean config state after every test via `reset_config` autouse fixture. +- MSColab tests spin up a real Flask-SocketIO subprocess on a random port. + +## Conventions + +- Flake8: max-line-length 120. Ignored: E124,E125,E402,W503,W504,A005. Excluded dirs: `mslib/msui/qt5/`, `mslib/mscolab/migrations/`. +- Codespell: exceptions in `codespell-ignored-lines.txt`. Ignore list: PRES, degreeE, doubleClick, indexIn, socio-economic, EMAC, emac. +- Qt UI files (`qt5/ui_*.py`) are generated from `.ui` — do not edit by hand. +- No CRLF in git. Whitespace at EOL in `tests/data/example.txt` and `docs/samples/flight-tracks/example.txt` is intentional.