diff --git a/AGENTS.md b/AGENTS.md index e97a19c..fc9464e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,132 +1,9 @@ -# AGENTS.md — Cloud agent workspace layout - -Instructions for AI agents and humans working in the **PyDevices cloud -workspace** (Cursor Cloud Agent VM). This complements -[CONTRIBUTING.md](CONTRIBUTING.md), [docs/github-presence.md](docs/github-presence.md), -and the shared directory convention in [docs/repo-layout.md](docs/repo-layout.md). - -On a developer laptop, repos usually live as siblings under a single parent -(e.g. `~/gh/pydevices/`). The cloud VM mirrors that layout under -`/home/ubuntu/gh/` using symlinks into `/agent/repos/`. - -**Automatic setup:** `.cursor/environment.json` in this repo runs -`scripts/cloud-workspace-install.sh`, `scripts/cloud-python-deps.sh`, and -`scripts/cloud-pydevices-examples-dev-env.sh` on each cloud VM boot (all idempotent). -After a successful install, agents should start real work immediately — no -separate “workspace configuration” chat. - -`cloud-workspace-install.sh`: -- Creates `/agent/repos` when missing and shallow-clones any absent PyDevices - siblings (Cursor’s `repositoryDependencies` expands GitHub token scope; it - does not always materialize those checkouts). -- Builds `~/gh/pydevices/` symlinks, shallow-clones MicroPython/CircuitPython, - inits `lvgl-bindings/lvgl`, and replaces an empty `lvgl-python/lvgl` - placeholder with the canonical symlink. -- Exits non-zero if required repos or LVGL are still missing. - -`cloud-python-deps.sh`: -- Installs `python3-venv` / `libsdl2-dev` via apt when the VM snapshot omits - them, recreates broken `.venv` leftovers, then installs pydevices-examples - (`requirements-dev.txt` + `pygame-ce` + `pydevices-lvgl`), `ruff` for - `palettes`/`pdwidgets`, and a `pydevices_siblings.pth` so examples import - canonical product sources from `pydevices` plus the sibling - `palettes`, `pdwidgets`, and `pygraphics` sources. - -`cloud-pydevices-examples-dev-env.sh`: -- Installs pydevices-examples `requirements.txt` (TestPyPI runtime stack for CPython). -- `micropython -m mip install`s desktop `board_config`, `palettes`, and `pdwidgets` into - `~/.micropython/lib` (`--no-mpy -t lib -i` PyDevices index for CP-shared source - installs; omit `--no-mpy` for MicroPython-only `.mpy` — see - pydevices `docs/install-workflows.md`). -- Appends a `pydevices-examples-env.sh` hook to `~/.bashrc` exporting `PATH` - (`pydevices-examples/bin`) plus `PYTHONPATH` / `MICROPYPATH` entries for - `pydevices-examples/lib/utils` and the canonical `pydevices` product paths. - Run examples from `pydevices-examples/lib/`. - -Use the **`pydevices-cloud-handoff`** skill (`/pydevices-cloud-handoff`) when -handing work from Cursor desktop to Cloud Agents. - -## Top-level layout - -``` -/home/ubuntu/gh/ -└── pydevices/ - ├── micropython a clone at the tag micropython-pydevices pins, the patch series applied - ├── circuitpython a clone at the pinned CircuitPython tag - ├── micropython-pydevices -> /agent/repos/micropython-pydevices - ├── audiodsp, pygraphics, lvgl-* ... -> /agent/repos/ (displayif, audioif, cameraif and usbhost are in micropython-pydevices/modules/) - ├── dotgithub -> /agent/repos/.github (this repo) - ├── pydevices -> /agent/repos/pydevices - ├── mpftp -> /agent/repos/mpftp - ├── PyDevices.github.io -> /agent/repos/PyDevices.github.io - ├── palettes -> /agent/repos/palettes - ├── pdwidgets -> /agent/repos/pdwidgets - ├── pydevices-examples -> /agent/repos/pydevices-examples - ├── android-template -> /agent/repos/android-template - └── pyscript-template -> /agent/repos/pyscript-template -``` - -**Not cloned locally:** `mip` — GitHub Actions owns sync and -release there; agents should not add it to this workspace unless explicitly -asked. - -## Workspace interior - -Every repository is a sibling at the workspace root, linked in from -`/agent/repos/`, not duplicated, and the two interpreter checkouts sit beside -them. That is the layout micropython-pydevices' presets assume (their paths -resolve two levels up from `manifests/`), and the one every build script in -the org defaults to: from `micropython/ports/`, upstream's own `make` -with `VARIANT_DIR=`, `BOARD_DIR=` and `FROZEN_MANIFEST=` pointing into -`micropython-pydevices`; for CircuitPython, the same `build_mp.py` with -`--interpreter circuitpython`, which builds each repo's `micropython.mk` as a -user C module. - -Upstream trees (`micropython/`, `circuitpython/`) are **read-only clones** in -this workspace. The MicroPython one carries a single local commit, the -PyDevices overlay, written by `micropython-pydevices/tools/prepare-micropython.sh`; -do not commit anything else inside them. - -### Upstream clones - -`scripts/cloud-workspace-install.sh` clones both at the pinned tags (blob-filtered, -so `git apply` still works) and runs `prepare-micropython.sh`. The lvgl-bindings -`lvgl` submodule is initialised there too, and `lvgl-python/lvgl` is a symlink to -it (one LVGL tree, never two): - -```bash -cd /home/ubuntu/gh/pydevices -git -C lvgl-bindings submodule update --init --depth 1 lvgl -rm -rf lvgl-python/lvgl # only if empty placeholder -ln -s ../lvgl-bindings/lvgl lvgl-python/lvgl -``` - -## Symlink safety - -When removing paths under `pydevices/`, delete **symlinks only** -(`rm path` on the link), never `rm -rf` through a symlink into -`/agent/repos/*` unless the intent is to destroy an owned repo. - -## GitHub auth — opening PRs on sibling repos - -Cloud Agents started from **`PyDevices/.github`** get an integration credential that can **push** branches into `/agent/repos/*` checkouts. When creating PRs on sibling repositories, use `gh pr create` with standard `GH_TOKEN` environment authentication: - -```bash -gh pr create -R PyDevices/ --base main --head --title "…" --body "…" -``` - -## Multi-Repository Command Iteration - -See [`.agents/rules/multi_repo_command_rule.md`](../.agents/rules/multi_repo_command_rule.md) -at the workspace root — the single home for this rule. - -## Known Environment Bugs - -- **Checkpoints swallowing tool responses**: If an agent issues a tool call exactly as a context checkpoint fires, the response can be silently lost, causing the agent to appear hung. If this happens, ask the agent to "try again". Tracked upstream at [google-antigravity/antigravity-cli#793](https://github.com/google-antigravity/antigravity-cli/issues/793). - -## Related docs - -- [micropython-pydevices](https://github.com/PyDevices/micropython-pydevices) — - presets, variants, boards and the patch series the builds use -- [lvgl-bindings CONTRIBUTING.md, Releasing](https://github.com/PyDevices/lvgl-bindings/blob/main/CONTRIBUTING.md#releasing) — - binding regeneration and `lvgl-python` release dispatch +# AGENTS.md + +- Tests: `python3 -m unittest discover -s tests -v` from the repo root. Lint is `ruff check scripts/ tests/`. +- `publishing-vN` tags are immutable: a bad one is fixed with a new `vN+1`, never by moving or deleting the tag. The reusable workflows are called by that tag, not a branch ([publishing automation](docs/publishing-automation.md), [operations runbook](docs/operations-runbook.md)). +- Don't hand-edit `RELEASE_HEALTH.md` or `release-health/data.json`; the release-health workflow rewrites them on every release report. +- Edit `data/repos_db.json`, never the generated markup, then run `python3 scripts/generate_sites.py`. It writes into the sibling repositories (`profile/README.md`, per-repo `.site/` trees, the pydevices ecosystem page), so run it with the repos checked out side by side ([README](README.md)). +- `.cursor/environment.json` lists the repos Cursor's cloud environment clones; keep it in step by hand when a public repository is added or retired. +- Repository layout and file-naming conventions, including the `MICROPYPATH` / `PYTHONPATH` search paths: [repo-layout](docs/repo-layout.md). Doc and docstring style: [doc-style](docs/doc-style.md), [docstrings](docs/docstrings.md). +- Other repositories' generated files are overwritten by their sync scripts, so change the generator, not the copy ([CONTRIBUTING.md](CONTRIBUTING.md#generated-files-and-sync-targets)). diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/scripts/cloud-python-deps.sh b/scripts/cloud-python-deps.sh index 0880bab..9924494 100755 --- a/scripts/cloud-python-deps.sh +++ b/scripts/cloud-python-deps.sh @@ -9,7 +9,7 @@ # - pydevices-examples (flagship) -> requirements-dev.txt + pygame-ce + native audio/LVGL bindings # - palettes pdwidgets -> ruff # -# Safe to run on every cloud VM boot (environment.json install). See AGENTS.md. +# Safe to run on every cloud VM boot (environment.json install). # Intentionally does NOT `set -e`: a single optional install (e.g. TestPyPI # pydevices-lvgl) must never abort VM startup for the whole team. Required # failures (no ensurepip after apt) still exit non-zero at the end. diff --git a/scripts/cloud-workspace-install.sh b/scripts/cloud-workspace-install.sh index 8281bab..83488a5 100755 --- a/scripts/cloud-workspace-install.sh +++ b/scripts/cloud-workspace-install.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash # Idempotent PyDevices cloud workspace layout: ~/gh/pydevices symlinks into /agent/repos. -# See AGENTS.md. Safe to run on every cloud VM boot (environment.json install). +# Safe to run on every cloud VM boot (environment.json install). # # Self-heals when Cursor did not materialize sibling checkouts under /agent/repos # (common for repo-file environments: repositoryDependencies expands the GitHub