# Contributing to Waggle Thank you for helping. This page covers the setup, the checks and how to propose a change. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) explains how the parts fit together. The rules below are the ones reviews check first. ## Prerequisites - Node.js `^20.19.0` or `>=22.12.0`, and npm. Node 22 is recommended; the release builds bundle 22.23.2. - Git. - For the desktop app only: a current Rust toolchain, plus the platform's Tauri prerequisites (on Windows, Visual Studio Build Tools with the C++ workload; see [docs/oss/build-windows.md](docs/oss/build-windows.md)). Python, Docker and a database server are not needed. ## Setup Clone the repository, then in its root: ```bash npm ci npm run build # type-checks the web UI and builds it into dist/ npm run dev:server # the sidecar on http://localhost:3333, serving dist/ ``` Open http://localhost:3333 and add a model in Settings → Models. - Workspace packages export their TypeScript source under the `source` condition, which tsx, Vitest, Vite and the sidecar build resolve. You do not need `npm run build:packages` before running or testing; it type-checks the packages and builds their `dist/` for publishing. - The sidecar registers the files in `dist/` when it starts. After `npm run build`, restart it, or new assets return 404. - `npm run dev:web` (Vite) cannot authenticate against the sidecar yet. Use the UI the sidecar serves. - Run one sidecar at a time. To keep test data apart from your own, start it with another data directory: `WAGGLE_DATA_DIR=/tmp/waggle-dev npm run dev:server`. Other entry points: ```bash npm run dev -w @waggle/cli # terminal REPL on the same memory and waggle.db (cd app && npm ci && npm run tauri:build:mac:arm64) # desktop app; also tauri:build:mac:x64, :win, :linux ``` ## Checks Run the checks that cover your change before you open a pull request. CI runs them too. ```bash npm run build:packages # tsc -b over every in-scope package npm run typecheck:web # the web UI npx tsc --noEmit --project app/tsconfig.json npm run typecheck:tests # test suites; advisory until existing errors are fixed npm run lint # root config; ignores apps/web (cd apps/web && npx eslint .) # web config npm run check:deps # every imported package is declared in its package.json npm run check:licenses # shipped dependencies allow MIT distribution npm test # root Vitest: packages, tests/, scripts/ (cd apps/web && npx vitest run) # web UI tests ``` Some checks fail before your change: [docs/oss/baseline.md](docs/oss/baseline.md) records the known failures and counts. A check that passes there must not start failing. End-to-end tests use Playwright (`npm run test:e2e`). They reuse a server already listening on :3333 and its data directory. For an isolated run set `WAGGLE_E2E_REUSE_EXISTING_SERVER=0` and a free `WAGGLE_E2E_PORT`. The e2e web server step runs `npm run build:all`, which rewrites `dist/`. Tests live in each package's `tests/` directory, in `apps/web/src` next to the code, and in the root `tests/`. New behavior needs a test; a bug fix needs a test that fails without the fix. ## Rules that reviews check first - No monetization: no tiers, trials, payments, license checks or upsell. - Memory goes through `MemoryStore` from `@waggle/memory-contract`. No SQL against a memory database, and no knowledge graph in this release. - Team mode (`packages/team-server`, `waggle-dance`, `worker`) is frozen, and self-learning is out of scope. - Every new dependency must allow MIT distribution: no GPL or AGPL code in shipped artifacts. Name its license in the commit message. - Analytics stay opt-in. Never commit a PostHog key or any other secret. - Platform-specific code needs Windows, macOS and Linux paths. End users must not need Python, Docker, a compiler or a developer Node.js install. - Security: secrets live in the vault, external input goes through the injection scanner, no `eval`, the Tauri IPC allowlist stays explicit, and SQL is parameterized. ## Code style - TypeScript in strict mode, ES modules, `.js` extensions in relative imports, and `import type` for types. - File names in `kebab-case.ts`; React components in `PascalCase.tsx`. - Match the style of the file you change. Do not reformat code you do not otherwise touch. - Search before you add a file: the module you need may already exist. - Code, comments, commit messages and documentation are in English. Write plainly. ## Commits and pull requests - One focused change per pull request. Describe what changed, why, and how you tested it. - Commit messages: `type(scope): summary` in the imperative, for example `fix(server): close the memory recall step when nothing is found`. Types: `feat`, `fix`, `refactor`, `test`, `docs`, `build`, `chore`, `perf`. - Keep commits small enough to review. Do not mix a refactor with a behavior change. - Never commit secrets, `.env` files or personal data. ## Reporting bugs and security issues Open an issue for bugs and feature proposals. Report security vulnerabilities privately as described in [SECURITY.md](SECURITY.md), not in a public issue. ## Troubleshooting **Windows: the sidecar fails to start with an esbuild error** such as `Cannot find module @esbuild/win32-x64`. npm skipped esbuild's platform binary. Install the binary that matches the esbuild version named in the error, without changing `package.json`: ```bash npm i @esbuild/win32-x64@ --no-save ``` **Assets return 404 after a build.** Restart the sidecar; see Setup. More user-facing problems are in [docs/guides/troubleshooting.md](docs/guides/troubleshooting.md).