AGENTS.md

1# Project Agent Instructions
2 
3Python environment:
4 
5- Always use the backend Poetry virtualenv (`backend-py3.10`) for Python commands.
6- Preferred invocation: `cd backend && poetry run <command>`.
7- If you need to activate directly, use Poetry to discover it in the current environment:
8  - `cd backend && poetry env activate` (then run the `source .../bin/activate` command it prints)
9 
10Testing policy:
11 
12- Always run backend tests after every code change: `cd backend && poetry run pytest`.
13- Always run type checking after every code change: `cd backend && poetry run pyright`.
14- Type checking policy: no new warnings in changed files (`pyright`).
15 
16## Frontend
17 
18- Frontend: `cd frontend && pnpm lint`
19 
20If changes touch both, run both sets.
21 
22## Prompt formatting
23 
24- Prefer triple-quoted strings (`"""..."""`) for multi-line prompt text.
25- For interpolated multi-line prompts, prefer a single triple-quoted f-string over concatenated string fragments.
26 
27# Hosted
28 
29The hosted version is on the `hosted` branch. The `hosted` branch connects to a saas backend, which is a seperate codebase at ../screenshot-to-code-saas
30 
31## Cursor Cloud specific instructions
32 
33Dependencies are refreshed automatically on startup (`poetry install` in `backend/`, `pnpm install` in `frontend/`); no manual install is needed.
34Cursor Cloud environment setup should run `bash /agent/repos/screenshot-to-code/scripts/cursor-cloud-install.sh`; the script changes to the repo root before installing so it works regardless of the startup working directory.
35 
36Services (see `README.md` for the canonical commands):
37- Backend (FastAPI + WebSocket): from `backend/`, `poetry run uvicorn main:app --reload --port 7001`.
38- Frontend (Vite/React): from `frontend/`, `pnpm dev` → open `http://localhost:5173`. The Vite dev server binds to `localhost` only, so use `http://localhost:5173`, not `http://127.0.0.1:5173` (the latter refuses the connection).
39- Frontend talks to the backend over a WebSocket (`VITE_WS_BACKEND_URL`, default `ws://127.0.0.1:7001`); generation streams over that socket, other routes are plain HTTP.
40 
41Non-obvious caveats:
42- `poetry` is installed under `~/.local/bin` and is on PATH for interactive shells (`.bashrc`) but not necessarily for non-interactive scripts; use the full path `~/.local/bin/poetry` if `poetry` is not found.
43- The Poetry virtualenv resolves to Python 3.12 (named like `backend-...-py3.12`), not 3.10 — `pyproject.toml` pins `^3.10`, which 3.12 satisfies. Just use `poetry run`.
44- Core feature (screenshot → code) requires at least one LLM key: set `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GEMINI_API_KEY` in `backend/.env` (restart backend after editing) or in the in-app Settings dialog. Without a key, generation fails fast with a "No OpenAI, Anthropic, or Gemini API key" message. `REPLICATE_API_KEY` (image gen/edit) only works via `backend/.env`, not the UI.
45- Playwright Chromium is pre-installed for the optional "Screenshot preview" tool; Settings shows it as "Available".
46- `pnpm install` prints an "Ignored build scripts (esbuild, puppeteer)" warning — this is harmless; Vite build/dev and tests work without approving builds.
47- `cd frontend && pnpm lint` currently reports pre-existing errors (e.g. `@typescript-eslint/no-explicit-any` in `generateCode.ts`) because lint runs with `--max-warnings 0`; these are baseline issues, not environment problems.
48