fix: improve terminal clipboard interactions

2026-08-13 00:20:10 +08:00
parent 6f6c554c90
commit 0f42cb3c6d
2 changed files with 107 additions and 16 deletions
@@ -0,0 +1,70 @@
+# 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.