{"owner":"Budibase","repo":"budibase","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"files":{"CLAUDE.md":"# Budibase Agent Guide\n\n## Architecture\n\n- Workspace uses Lerna monorepo with packages in `packages/`\n- Main packages: server, worker, backend-core, frontend-core, client, builder, shared-core, bbui\n- Use `@budibase/` scoped imports between packages\n- Backend packages (NodeJS): server, worker, backend-core\n- Frontend packages (browser): builder, frontend-core, bbui\n- Shared (NodeJS and browser): shared-core\n\n## Build/Test Commands\n\n- Build: `yarn build`\n- Lint: `yarn lint` (check) or `yarn lint:fix` (fix)\n- Test: `yarn test <filename>` run inside of a packages/\\* directory\n- Type check: `yarn check:types`\n- packages/server tests: if you're working on a test that uses the\n  `datasourceDescribe` function, that means you can pass `DATASOURCE=` as an env\n  var to the test to narrow it down to one specific database. The database strings\n  you can use can be found on `DatabaseName` in `packages/server/src/integrations/tests/utils/index.ts`\n\n## Code Style\n\n- No semicolons, double quotes, 2-space tabs (see .prettierrc.json)\n- Use TypeScript strict mode with consistent-type-imports\n- Imports: Group external imports first, then internal `@budibase/*` packages\n- Assume the target Node version from the repo root `.nvmrc` when writing or reviewing code\n- Variables: camelCase, prefix unused with `_`\n- Functions: Prefer arrow functions, use async/await over Promises\n- Error handling: Use try/catch\n- Types: Use `interface` for objects, `type` for unions/primitives, do NOT cast to any or unknown.\n- Do not add backwards compatibility paths or broad \"handle every scenario\" logic unless explicitly instructed to do so for the task.\n- Testing: Jest framework, use describe/it structure, mock external services\n  using `nock`.\n- Only comment when it's really necessary to explain an unclear behaviour.\n- Never use console.log in tests, the output will not be visible in STDOUT\n  when you run the tests. It is a waste of time.\n- In application code use console.log instead of pino the logging framework.\n  We have made it so that console.log statements are redirected to pino.\n- When you're writing tests, you don't need to assert or do conditional checks\n  on intermediate states. Just assert the final outcome\n  against, provided there are no type errors.\n- Avoid adding nested ternary statements.\n- Prefer a svelte5 approach over svelte4.\n- Don't use // @ts-nocheck when asked to fix type errors.\n- When writing tests involving a URL, use example.com as the domain.\n- Use object parameters for functions with multiple inputs. This is required for\n  new or refactored functions; only retain positional parameters when preserving\n  an existing external API.\n\n## Test style - packages/server\n\n- When building automations utilise the `createAutomationBuilder` function\n  found in `packages/server/src/automations/tests/utilities/AutomationTestBuilder.ts`\n- When building tables, datasources, queries and various other Budibase resources check for functions like `basicTable`\n  found in `packages/server/src/tests/utilities/structures.ts` - use these to create a basic table, you can provide\n  extended configuration if required through the `extra` prop.\n- Use `TestConfiguration` in `packages/server/src/tests/TestConfiguration.ts` for every API test case -\n  this can be used to access the test API under `new TestConfiguration().api`, a list of functions and\n  request/response types can be found in `packages/server/src/tests/utilities/api`.\n\n## Git\n\nNever auto-commit changes unless explicitly asked to do so. You may ask permission to commit.\nEach commit requires permission.\n\nNever auto-push changes unless explicitly asked to do so. You may ask permission to push.\nEach push requires permission.\n\nNever auto-stage or add changes unless explicitly asked to do so. As a developer I want to review the changes that the LLM has made.\nNever unstage changes.\n\nFor example, if I command `git add, commit, push` go ahead and do that once. Any subsequent changes will require permission. You may ask for permission on a per commit basis.\n\n## Pull requests\n\n- Always respect the format of pull_request_template.md. Some sections may not\n  be required, you are free to ignore them. Don't add new sections, though.\n- When you open a pull request, always open it as a draft so that it can be\n  reviewed by a human.\n- Before opening a pull request, always make sure that the branch you're pushing\n  is up to date with master.\n- If you're working on a bug, the name of the PR should start with the bug ID\n  in square brackets, e.g. [BUDI-1234]. The link to the bug should go into the\n  \"Addresses\" section of pull_request_template.md.\n\n## Browser use\n\n- If you're browsing the Budibase product in a browser, you can find\n  comprehensive documentation at https://docs.budibase.com\n- The local URL for the development server is http://localhost:10000. Before\n  running `yarn dev`, check to see if the development server is already running.\n- The default login for local development is email \"local@budibase.com\" and\n  password \"cheekychuckles\".\n- The product is split up by app, so to find things like data sources and\n  automations you must first make sure to select an app.\n\n## LiteLLM\n\n- The LiteLLM API is available when in local development at localhost:4000\n- The auth token is `budibase`\n\n## Misc\n\n- When creating or switching branches, make sure the branch is up to date with\n  the remote on GitHub. Don't work on old code.\n\n## Cursor Cloud specific instructions\n\n### Services overview\n\n| Service                  | Port  | Notes                                                          |\n| ------------------------ | ----- | -------------------------------------------------------------- |\n| Nginx proxy (main entry) | 10000 | Routes to builder, server, worker, CouchDB, MinIO              |\n| Builder (Vite/Svelte)    | 3000  | Frontend dev server                                            |\n| Server (Koa)             | 4001  | Backend API for apps                                           |\n| Worker                   | 4002  | Background jobs; note `.env` sets `WORKER_PORT=4002`, not 4003 |\n| CouchDB                  | 4005  | Primary database                                               |\n| CouchDB SQS              | 4006  |                                                                |\n| Redis                    | 6379  | Cache, sessions, queues                                        |\n| MinIO                    | 4004  | S3-compatible object storage                                   |\n| LiteLLM (optional)       | 4000  | AI proxy; see `## LiteLLM` section above for auth token        |\n\n### Starting the dev environment\n\n1. Docker must be running before `yarn dev`. The dev stack (CouchDB, Redis, MinIO, Nginx, optionally LiteLLM) is started automatically by `yarn dev` via `packages/server/scripts/dev/manage.js`.\n2. `yarn dev` runs: `dev:init` (generates `.env`), `kill-all` (frees ports), `prebuild`, then starts server + worker + builder via `lerna run --stream dev`.\n3. The worker listens on port **4002** (set by `WORKER_PORT` in `.env`), not 4003. Health check: `curl http://localhost:4002/health`.\n4. Server health check: `curl http://localhost:4001/health`.\n5. Full app is accessible at `http://localhost:10000` via the Nginx proxy.\n\n### Running tests\n\n- Run package-specific tests from inside the package directory: `cd packages/<pkg> && yarn test <filename>`.\n- `packages/server` and `packages/backend-core` tests use `scripts/test.sh` wrappers around Jest.\n- `shared-core` and `string-templates` tests run directly via `jest`.\n\n### Docker in Cloud VM\n\nDocker is installed and configured with `fuse-overlayfs` storage driver and `iptables-legacy` for the nested container environment. The Docker daemon must be started with `sudo dockerd` before use. Socket permissions are set via `chmod 666 /var/run/docker.sock` so `docker` commands work without `sudo`.\n\n### Gotchas\n\n- `lerna` is a devDependency and not globally installed. The `yarn dev` script works because `yarn` resolves local bins, but if running `lerna` directly, use `npx lerna` or `yarn lerna`.\n- The `postinstall` hook runs `husky install` for git hooks. Pre-push hook requires `git-lfs`.\n- Build is required before `yarn dev` for the first time: `yarn build`. Subsequent runs use nodemon for hot-reload of server/worker, but changes to shared packages (types, shared-core, backend-core) may require a rebuild.\n"}}