cursornew2026/AGENTS.md

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:

  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.