# Repository guidance

## Project overview

WebSSH is a Python 3.10+ web SSH client. Tornado serves the HTTP and WebSocket
endpoints, Paramiko manages SSH connections, and xterm.js renders the terminal
in the browser.

## Repository layout

- `webssh/main.py`: application entry point and route wiring.
- `webssh/handler.py`: HTTP/WebSocket handlers and SSH connection setup.
- `webssh/worker.py`: asynchronous relay between Tornado and Paramiko channels.
- `webssh/settings.py`: CLI options and application/server configuration.
- `webssh/auth.py`, `webssh/storage.py`, `webssh/crypto.py`: authentication and
  persistent saved-connection data.
- `webssh/templates/` and `webssh/static/`: browser UI.
- `tests/`: pytest/unittest test suite; `tests/sshserver.py` provides the local
  Paramiko-based integration server.

## Setup and development commands

Use Python 3.10, 3.11, or 3.12.

```bash
python -m pip install -r requirements.txt
python -m pip install -e .
python run.py                         # listens on 127.0.0.1:8888
python run.py --port=8888 --debug=True --data-dir=./data
```

Install test tools with `python -m pip install pytest pytest-cov ruff`. Before
handing off a change, run the checks relevant to it:

```bash
python -m pytest tests
python -m pytest tests/test_app.py    # focused example
python -m pytest --cov=webssh
ruff check .
```

The legacy Flake8 configuration in `setup.cfg` uses a maximum line length of
79 and excludes tests and `__init__.py` files.

## Implementation constraints

- Do not block Tornado's IOLoop. Paramiko connection work is blocking and must
  run through the existing handler `ThreadPoolExecutor` pattern.
- Preserve locking around auth data, saved connections, and host-key mutation;
  these objects are accessed from multiple threads.
- New HTTP endpoints should include `MixinHandler`. Protect private endpoints
  with `@tornado.web.authenticated` and retain the existing origin, XSRF, IP,
  and session checks.
- Treat credentials, private keys, cookie secrets, and saved connection data as
  sensitive. Never log or expose them to the browser. Persistent auth and
  connection files must retain mode `0o600`.
- Keep saved-password encryption compatible with the cookie secret and do not
  silently reuse a credential when host, port, or username changes.
- Keep changes compatible with all supported Python versions and avoid adding
  dependencies unless the task requires them.

## Testing expectations

- Add or update focused tests for behavior changes and regressions.
- Use the local mock SSH server for SSH authentication and connection flows;
  tests must not depend on external SSH hosts or network services.
- For frontend or WebSocket changes, cover both the server handler behavior and
  the corresponding browser-side message contract when applicable.
- Do not commit generated runtime state such as `auth.json`, `connections.json`,
  cookie secrets, coverage output, caches, or local data directories.