Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
101 lines (70 loc) · 4.22 KB

CONTRIBUTING.md

File metadata and controls

101 lines (70 loc) · 4.22 KB
Raw

Contributing

Thank you for investing time in W Agent. This project is intended as a serious, self-hosted system—not a demo toy. Contributions should preserve safety defaults, keep the provider adapter clean, and leave CI green.

Before you start

  1. Read docs/security.md. Changes that weaken injection handling, approval, or rate limits need explicit justification.
  2. Read docs/architecture.md. Prefer extending WhatsAppProvider over leaking Baileys or Graph types into agent/MCP code.
  3. Use a dedicated WhatsApp number for any live bridge testing. Ban risk is real (docs/providers.md).

Development setup

Requirements: Node.js 22+, pnpm 9+, Docker (Compose services and Vitest testcontainers).

git clone https://github.com/Chessing234/w-agent.git
cd w-agent
pnpm install
cp .env.example .env
# Set at least OPENAI_API_KEY for agent/embed paths you exercise locally

docker compose up -d postgres redis
pnpm migrate

pnpm dev                 # bridge + workers
pnpm dashboard:dev       # optional UI on DASHBOARD_PORT

Useful checks:

pnpm lint
pnpm typecheck
pnpm test                # needs Docker for Postgres suites
pnpm test:coverage       # enforces ≥80% lines/functions on src/safety + src/agent

Project conventions

Area Expectation
Language TypeScript (NodeNext ESM), Zod for env config
Formatting Prettier via ESLint (pnpm lint:fix)
Logging Pino; no secrets in log fields
WhatsApp I/O Only through WhatsAppProvider
Outbound Draft/outbox by default; do not add ungated send paths
Migrations SQL via node-pg-migrate; both Up and Down sections
Tests Vitest; Postgres via @testcontainers/postgresql for storage/lifecycle

Provider adapter rule

If you add WhatsApp capability:

  1. Extend the interface in src/bridge/provider.ts when the capability is cross-backend.
  2. Implement on Baileys and/or Cloud API as appropriate; stub or reject clearly when unsupported.
  3. Keep src/agent, src/queue, and src/mcp free of vendor SDK imports.

Safety rule

Do not “fix” user friction by:

  • Skipping the injection guard on inbound third-party content
  • Auto-approving drafts globally
  • Disabling quiet hours / daily caps by default
  • Returning raw env secrets to the model

If a feature needs a dangerous escape hatch, gate it behind an explicit, documented env flag defaulting to off.

Tests

Suite Role
Unit (tests/*.test.ts) Engagement matrix, guard classifier, rate limiter, tools, MCP, Cloud API normalize
Storage / lifecycle Real Postgres (testcontainers): persist, outbox, embed/search, full draft→approve→send
Coverage gate src/safety/** and src/agent/** (OpenAI SDK adapter provider.ts excluded)

When changing behavior, add or update tests in the same PR. CI runs lint, typecheck, and pnpm test:coverage on Node 22.

Pull requests

  1. Scope — One concern per PR when practical (feature, fix, docs, chore).
  2. Description — What changed, why, risk notes (especially send path / auth / migrations).
  3. Verification — Commands you ran (pnpm lint, pnpm test, manual QR check, etc.).
  4. Docs — Update README or docs/ when behavior or setup changes.
  5. Secrets — Never commit .env, auth directories, tokens, or production database dumps.

Commit messages: short imperative summary; explain why in the body when the diff is non-obvious.

Issues

  • Bug reports: expected vs actual, version/commit, provider (baileys / meta), relevant logs with secrets redacted.
  • Feature requests: problem statement first; propose how it fits the provider adapter and approval model.
  • Ban / disconnect reports against Baileys: useful as operational data, but usually not a patchable application CVE—see docs/security.md.

Code of conduct (summary)

Be precise and respectful in review. Assume good intent; require evidence for security-sensitive claims. Harassment or deliberate sabotage of safety controls will not be accepted.

License

By contributing, you agree that your contributions are licensed under the same MIT License that covers this repository.