5.7 KiB
Contributing to Waggle
Thank you for helping. This page covers the setup, the checks and how to propose a change.
docs/ARCHITECTURE.md explains how the parts fit together. The rules below are the ones reviews check first.
Prerequisites
- Node.js
^20.19.0or>=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).
Python, Docker and a database server are not needed.
Setup
Clone the repository, then in its root:
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
sourcecondition, which tsx, Vitest, Vite and the sidecar build resolve. You do not neednpm run build:packagesbefore running or testing; it type-checks the packages and builds theirdist/for publishing. - The sidecar registers the files in
dist/when it starts. Afternpm 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:
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.
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 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
MemoryStorefrom@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,
.jsextensions in relative imports, andimport typefor types. - File names in
kebab-case.ts; React components inPascalCase.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): summaryin the imperative, for examplefix(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,
.envfiles 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, 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:
npm i @esbuild/win32-x64@<version> --no-save
Assets return 404 after a build. Restart the sidecar; see Setup.
More user-facing problems are in docs/guides/troubleshooting.md.