Files
waggle-os/CONTRIBUTING.md
2026-11-04 10:41:40 +01:00

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.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).

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 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:

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 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, 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.