Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
106 lines (79 loc) · 3.88 KB

CONTRIBUTING.md

File metadata and controls

106 lines (79 loc) · 3.88 KB

Contributing to AgentLink

AgentLink is the connective tissue between AI agent runtimes — a secure, local-first agent network platform. Contributions that improve correctness, security, and reliability are most welcome. Contributions that add complexity without clear benefit are not.

Repo structure

apps/
  api/        FastAPI server — enrollment, task dispatch, audit, operator auth
  web/        Next.js operator UI — task queue, audit log, node detail views
  node/       Node runtime — the enrollable agent peer process
packages/
  config/     Shared vitest/tsconfig base config
  protocol/   Shared TypeScript types (wire format, task schema, node models)
  utils/      Shared utilities
adapters/
  generic-rest/   Adapter for generic REST-based agent backends
  openclaw/        Adapter for OpenClaw-compatible backends
docs/         Architecture notes, milestone specs, ADRs
scripts/
  release-gate.js   Full-stack validation script (single source of CI truth)
.github/
  workflows/ci.yml  CI pipeline

Local setup

Requirements: Node >= 20, pnpm >= 9, Python >= 3.11.

# JavaScript/TypeScript
pnpm install

# Python API
cd apps/api
pip install -r requirements.txt

Development workflow

Run the full release gate before pushing:

node scripts/release-gate.js

This runs (in order):

  1. pnpm install --frozen-lockfile
  2. pnpm run build
  3. pnpm run typecheck
  4. pnpm run coverage (web + node coverage thresholds enforced)
  5. pip install -r apps/api/requirements.txt
  6. python -m pytest (API tests + coverage threshold enforced)

All six steps must pass. CI runs this exact script.

Individual test commands:

pnpm --filter @agentlink/web run test        # web unit tests
pnpm --filter @agentlink/node run test       # node unit tests
cd apps/api && python -m pytest              # API tests

Pull requests

  • Target main.
  • Keep PRs focused — one logical change per PR.
  • All CI checks must pass before merge.
  • New behavior must include tests. Bug fixes should add a regression test.
  • Fill out the PR template honestly.

Testing expectations

  • API tests live in apps/api/tests/. Use real DB (SQLite in-memory via pytest fixtures). Do not mock the database.
  • Web/node tests live alongside source in __tests__/ directories. Pure functions go in src/lib/; test them directly.
  • Coverage thresholds are enforced by the release gate. Do not lower them without a documented reason.

Security expectations

  • Do not add unauthenticated endpoints.
  • Do not log secrets, tokens, or credentials.
  • Do not disable or bypass policy enforcement without operator approval.
  • If you find a vulnerability, follow the process in SECURITY.md.

Style and scope

  • TypeScript: strict mode, no any without justification.
  • Python: follow existing patterns; no new frameworks without discussion.
  • Do not add dependencies without a clear reason. Prefer the standard library.
  • Do not refactor code that is not directly related to your change.
  • Do not add comments that restate what the code already says.

What not to change casually

  • packages/protocol/ — wire format changes affect all layers simultaneously.
  • apps/api/app/db/repository.py — query changes can break coverage thresholds or expose auth bugs.
  • .github/workflows/ci.yml and scripts/release-gate.js — the CI contract.
  • Coverage thresholds in apps/web/vitest.config.ts, apps/api/pyproject.toml, and packages/*/vitest.config.ts.

Proposing major architectural changes

Open a GitHub Discussion or an Issue with the architecture label before writing code. Describe the problem, the proposed change, and what you expect to break. A brief ADR in docs/ is appropriate for changes that affect the protocol, the auth model, or the task execution loop.

License

By contributing, you agree your contributions are licensed under Apache-2.0 (see LICENSE).