AGENTS.md · fossasia/visdom

Sections

1. Setup
2. Code Style
3. Do Not
4. Pitfalls
5. Testing
6. PR Checklist
7. Ask Before
8. Context & Skills

First lines (shown under the repo's Apache-2.0 license)

<!-- SPDX-License-Identifier: Apache-2.0
     https://www.apache.org/licenses/LICENSE-2.0 -->

# AGENTS instructions

Visdom: Python client + Tornado server + React frontend for live data visualization.
Version `0.3.0` · Python >= 3.12 · Apache 2.0

## Setup

- Install Python: `pip install -e . && pip install -r test-requirements.txt`
- Build frontend: `yarn && yarn run build`
- Install hooks: `pip install pre-commit && pre-commit install`

## Code Style

- Format Python: `black py` (v23.1.0, CI-enforced)
- Lint JS: `npm run lint`
- Format JS/CSS/JSON: Prettier (v2.6.2)
- Add Apache License headers to all new files (see `context/backend.md`)

## Do Not

- Edit files in `py/visdom/static/` — auto-built by CI
- Edit legacy Lua/Torch code in `th/`
- Commit secrets, credentials, or `COOKIE_SECRET`
- Push directly to `master`
- Skip pre-commit hooks (`--no-verify`)

## Pitfalls

- Handlers in `web_handlers.py` copy app attributes in `initialize()` — do not refactor to `self.app`
- Always decorate handler methods with `@check_auth` — omitting it creates an auth bypass
- Every socket feature must work in both WebSocket and polling modes
- Do not "fix" direct state mutation in `main.js` (`storeData.layout = layout`) — intentional
- `TextPane.js` uses `innerHTML` by design — do not expose server without auth
- Sanitize environment names via `escape_eid()`, verify paths stay within `env_path`

## Testing

- Python unit tests: `pytest -m "not server"` (config in `pyproject.toml`, suite in `py/tests/`)
- Fast loop: `pytest -m unit` — CI runs this as a gate, so mark every new file with a module-level
  `pytestmark`; see `context/testing.md` for which marker and where the file goes
- Install browser once: `npx playwright install chromium`
- Run E2E tests: `npm test` and `npm run test:polling`
- Visual tests: `npm run test:init` then `npm run test:visual`
- Pre-commit: `pre-commit run --all-files`

## PR Checklist

- Branch from `master`; add `pytest` tests in `py/tests/` for Python code and Playwright tests for frontend behavior
- New test file: put it in `py/tests/unit/` or `py/tests/integration/`, and give it the matching
  `pytestmark` — CI runs `-m unit` as a gate, so an unmarked file is in neither job
- Update `README` for API changes, `__init__.pyi` for interface changes
- Run linters, do not commit `py/visdom/static/`

## Ask Before

- Changing API endpoints, message protocol, or auth
- Adding Python or Node.js dependencies
- Large cross-component refactors

## Context & Skills

- `context/` — architecture, backend, frontend, testing
- `skills/` — adding-pane, websocket-flow, playwright-testing, release-process