From be050d96064560a22093a8a82c1a5ad66a8ea732 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Flor=C3=AAncio?= Date: Sun, 24 May 2026 14:46:30 +0100 Subject: [PATCH] docs: add remote cloud environment instructions (#1061) --- AGENTS.md | 8 +++++++- docs/remote-cloud-environment.md | 35 ++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+), 1 deletion(-) create mode 100644 docs/remote-cloud-environment.md diff --git a/AGENTS.md b/AGENTS.md index a944a11cb2..c154c64399 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -101,4 +101,10 @@ When a change is scoped to a single subtree, update the scoped `AGENTS.md` inste --- -**Last Updated**: 2026-05-16 +## Remote cloud environment + +For developing in ephemeral cloud VMs (Cursor Cloud, Codex, GitHub Codespaces, etc.), see [`docs/remote-cloud-environment.md`](docs/remote-cloud-environment.md) — covers runtime requirements, generated-file gotchas, and dev-mode setup. + +--- + +**Last Updated**: 2026-05-24 diff --git a/docs/remote-cloud-environment.md b/docs/remote-cloud-environment.md new file mode 100644 index 0000000000..ae5b069f5e --- /dev/null +++ b/docs/remote-cloud-environment.md @@ -0,0 +1,35 @@ +# Remote Cloud Environment Instructions + +Setup notes and caveats for developing Kandev in ephemeral cloud VMs (Cursor Cloud, Codex, GitHub Codespaces, or similar sandboxed environments). + +## Runtime requirements + +- **Go 1.26** — install to `/usr/local/go` and ensure `PATH` includes `/usr/local/go/bin`. +- **Node.js 24** — use `nvm install 24 && nvm use 24`. +- **pnpm 9.15.9** — matches `packageManager` in `apps/package.json`. Install with `npm install -g pnpm@9.15.9`. +- **golangci-lint v2** — required for `make lint-backend`. Install with `go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest`. +- **gcc** — required for CGO (SQLite FTS5). Pre-installed on most Ubuntu-based cloud VMs. + +## Generated files before typecheck + +Before running `make typecheck`, you must generate two files that are gitignored: + +```bash +node apps/web/scripts/generate-release-notes.mjs +node apps/web/scripts/generate-changelog.mjs +``` + +Without these, `tsc` fails with missing module errors for `@/generated/release-notes.json` and `@/generated/changelog.json`. + +## Running dev mode + +`make dev` from the repo root builds the backend and starts both the Go backend (port 38429) and Next.js frontend (port 37429). The CLI launcher sets `KANDEV_DEBUG_DEV_MODE=true` which activates the `dev` profile from `profiles.yaml`, enabling mock agent and other dev conveniences. No external services (database, message queue, Docker) are needed — SQLite is embedded and the event bus runs in-memory. + +## Key commands + +All documented in the root `Makefile`: +- `make dev` — build + start backend + web (dev mode) +- `make test` — backend (Go) + web (vitest) + CLI tests +- `make lint` — golangci-lint + ESLint +- `make typecheck` — TypeScript type-checking across all apps +- `make fmt` — format all code (run before lint to avoid false positives)