diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..190f27e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,131 @@ +# Contributing to Waggle + +Thank you for helping. This page covers the setup, the checks and how to propose a change. + +**Read [AGENTS.md](AGENTS.md) before you change code.** It is the operating contract for this +repository, for people and coding agents alike: what is in scope, the rules that must not be +broken, and the commands that verify a change. The decisions behind it are in +[docs/oss/adr/](docs/oss/adr/README.md). [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) explains +how the parts fit together. + +## 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; see AGENTS.md section 4 +``` + +## 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 + +The full list is in [AGENTS.md](AGENTS.md), section 3. In short: + +- 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 constraints (secrets in the vault, the injection scanner on external input, no + `eval`, an explicit Tauri IPC allowlist, parameterized SQL) are in AGENTS.md, section 8. + +## 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: [AGENTS.md](AGENTS.md), section 9, lists modules that 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). diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 3f2bebf..6e4bc75 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,172 +1,3 @@ -# Contributing to Waggle +# Contributing -## Prerequisites - -- **Node.js 20+** (required) -- **Rust toolchain** (only for the desktop app -- `app/` package) -- **Docker** (only for team mode tests -- PostgreSQL and Redis) - -## Setup - -```bash -git clone waggle-os # the public repository location is not decided yet -cd waggle-os -npm install -``` - -## Running the App - -```bash -# Local server / sidecar (http://localhost:3333) -cd packages/server && npx tsx src/local/start.ts -# — or, from the repo root: npm run dev:server - -# Web app (http://localhost:8080) -npm run dev # — or: npm run dev:web - -# Desktop app (requires Rust) -cd app && npm run tauri dev - -# CLI REPL -cd packages/cli && npx tsx src/index.ts -``` - -## Running Tests - -Tests are the product's safety net. All PRs must pass the full test suite. - -```bash -# Run all tests (3000+ across 190+ files) -npx vitest run - -# Watch mode during development -npx vitest - -# Run tests for a specific package -npx vitest run packages/core - -# Run a specific test file -npx vitest run packages/agent/src/__tests__/tools.test.ts - -# Coverage report -npx vitest run --coverage -``` - -### Test Requirements - -- All existing tests must pass before submitting a PR -- New features require accompanying tests -- Bug fixes require a regression test -- Team mode tests require Docker services running (`docker compose up -d`) - -### Test Organization - -Tests live alongside source files in `__tests__/` directories or as `.test.ts` siblings. The monorepo uses a single Vitest config at the root. - -## Pull Request Process - -1. **Fork** the repository and create a feature branch from `main` -2. **Read the CLAUDE.md** for execution rules and product truths -3. **Make your changes** following the slice-based approach (one focused change per PR) -4. **Write tests** for new functionality -5. **Run the full test suite**: `npx vitest run` -6. **Verify the build**: `npx tsc --noEmit` -7. **Submit a pull request** against `main` -8. **Describe your changes**: what was added, what was preserved, what was tested - -### PR Title Format - -Use descriptive titles that indicate the type of change: - -- `feat: add Notion connector` -- new feature -- `fix: memory search scope filtering` -- bug fix -- `refactor: extract FrameStore from MindDB` -- code restructuring -- `test: add coverage for approval gates` -- test additions -- `docs: update API reference` -- documentation - -## Code Style - -### TypeScript - -- ESM modules (`"type": "module"` in package.json) -- Explicit imports (no barrel re-exports) -- Strict TypeScript (`strict: true`) -- Use `type` imports where possible: `import type { Foo } from './foo.js'` -- Include `.js` extensions in imports (ESM requirement) - -### File Organization - -- One concept per file where practical -- Co-locate tests: `foo.ts` and `__tests__/foo.test.ts` -- Route files export a Fastify plugin async function -- Types go in the `@waggle/shared` package if used across packages - -### Naming Conventions - -- Files: `kebab-case.ts` -- Types/Interfaces: `PascalCase` -- Functions/variables: `camelCase` -- Constants: `UPPER_SNAKE_CASE` -- Route handlers: descriptive comments with HTTP method and path - -### Error Handling - -- Route handlers catch errors and return appropriate HTTP status codes -- Non-critical operations use try/catch with empty catch (logging is acceptable) -- Critical operations throw with descriptive error messages -- Avoid swallowing errors silently in core logic - -## Package Structure - -### Adding to an Existing Package - -1. Add your source file in the appropriate directory -2. Export from the package's `index.ts` if it's a public API -3. Add tests in the `__tests__/` directory -4. Run `npx vitest run packages/` to verify - -### Key Directories - -``` -packages// - src/ - index.ts # Public exports - __tests__/ # Test files - package.json # Package metadata - tsconfig.json # TypeScript config -``` - -## Product Rules - -Read `CLAUDE.md` in the repo root for the full execution protocol. Key rules: - -- **Waggle is workspace-native** -- do not collapse into a global chat -- **Memory is a product primitive** -- do not treat it as decorative -- **Tool transparency matters** -- users see what the agent does -- **Approval gates are required** for sensitive operations -- **No scope reduction without approval** -- do not simplify features "for now" -- **Tests are part of the product** -- not an afterthought - -## Troubleshooting - -### Windows: sidecar fails to start with an esbuild platform error - -The Fastify sidecar runs through `tsx`, which uses esbuild. On a clean Windows -machine the platform-specific esbuild binary is sometimes not resolved, and -`npm run dev:server` (or `npx tsx src/local/start.ts`) fails with an error like -`Cannot find module @esbuild/win32-x64` or an esbuild version/host mismatch. - -Fix it by installing the matching Windows esbuild binary without adding it to -`package.json`: - -```bash -npm i @esbuild/win32-x64@0.28.0 --no-save -``` - -This affects **Windows only** — macOS and Linux resolve their esbuild binaries -normally. The version should match the esbuild your install resolved; `0.28.0` -is the known-good pin for the sidecar. - -## Questions? - -Open an issue for architecture questions, feature proposals, or bug reports. +Moved to [CONTRIBUTING.md](../CONTRIBUTING.md) in the repository root.