Files
waggle-os/docs/CONTRIBUTING.md
shumeiko.it 16eaf01e14 chore: scrub personal names, maintainer URLs and local paths (P2.2)
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.
2026-11-01 00:50:13 +01:00

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.