36 lines
3.1 KiB
Markdown
36 lines
3.1 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
- `backend/`: FastAPI admin service (entry `run.py`), configuration in `app/config.py`, SQLite state in `cursorpro.db`, and runtime helpers `start.sh`/`stop.sh`. Static assets live under `static/` with HTML in `templates/`.
|
|
- `extension/`: Packaged VS Code extension; `.vsix` bundles for install, compiled logic under `out/` (API client, webview, status bar) and assets in `media/`. Code is obfuscated; prefer small, deliberate edits and keep filenames stable.
|
|
- `docs/`: Reference plans (e.g., `PLAN_3.0_MITM.md`) for integration context.
|
|
- Deobfuscation utilities (`deobfuscate*.js`, `*_decoded_map.json`, `deobfuscated*/`): Node scripts and generated maps used to unpack/inspect extension bundles; regenerate outputs in place to keep downstream scripts aligned.
|
|
|
|
## Build, Test, and Development Commands
|
|
- Backend setup/run:
|
|
```bash
|
|
cd backend
|
|
python3 -m venv venv && source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
RELOAD=true PORT=8000 python run.py # dev server with hot reload
|
|
./start.sh && tail -f cursorpro.log # managed start (PID + log)
|
|
./stop.sh # graceful stop
|
|
```
|
|
- Extension smoke: install a packaged build for manual checks (`code --install-extension extension/cursorpro-0.4.5.vsix`), then verify the panel/status bar.
|
|
|
|
## Coding Style & Naming Conventions
|
|
- Python: follow PEP 8 with 4-space indents; snake_case for functions/variables, PascalCase for SQLAlchemy models and Pydantic schemas, and typed responses on FastAPI routes. Keep configuration centralized in `app/config.py` and reuse `settings` instead of new globals.
|
|
- JavaScript: extension code is CommonJS and minified; keep changes minimal and well-commented, preserving existing exports. JSON/asset filenames use lower_snake_case; avoid renaming unless necessary.
|
|
|
|
## Testing Guidelines
|
|
- No automated suite yet; at minimum hit the backend health check and auth flows: `curl http://127.0.0.1:8000/health` and exercise `/docs` to validate tokens and admin endpoints. Add pytest + httpx API tests when modifying routers/services, using an isolated SQLite file.
|
|
- For extension edits, perform VS Code smoke tests (activation on startup, webview render, status bar updates, account switch) and review the “CursorPro” output channel for errors.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
- Commits: concise, imperative subject lines (e.g., “Add admin batch upload validation”) with scoped changes. Call out config or database migrations explicitly.
|
|
- PRs: include purpose, key changes, test evidence (commands run, screenshots for UI tweaks), and any new env vars or secrets required for deployment.
|
|
|
|
## Security & Configuration Tips
|
|
- Do not commit real tokens, API keys, or database snapshots; scrub `app/config.py`, `token.json`, and `cursorpro.db` before sharing. Prefer `.env`/environment overrides for secrets alongside `HOST`/`PORT`/`RELOAD`.
|
|
- Backend listens on `0.0.0.0` by default; bind to localhost during development. Protect external admin APIs that use the `X-API-Token` header and rotate credentials if exposed.
|