# 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 https://github.com/marolinik/waggle-os.git
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.