Sample data in tests, prompts and UI placeholders uses Alex Morgan instead of the maintainer's name; decision attributions say "owner". Personal details in two test fixtures are replaced. Local paths (D:/Projects/...) and paths into the maintainer's planning repository are reworded. Clone and install URLs in CONTRIBUTING.md and the getting started guide use placeholders until the public repository location is decided (Q9). The Benchmarks page no longer names the maintainer's hive-mind repository, and the upstream fixes log names the main Waggle repository instead of an internal git host.
173 lines
5.1 KiB
Markdown
173 lines
5.1 KiB
Markdown
# Contributing to Waggle
|
|
|
|
## 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 <repository-url> 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/<name>` to verify
|
|
|
|
### Key Directories
|
|
|
|
```
|
|
packages/<name>/
|
|
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.
|