CONTRIBUTING.md

Contributing to Warden

Prerequisites

• Node.js >= 20.0.0
• pnpm (install via npm install -g pnpm)
• An Anthropic API key for running skills

Setup

pnpm install
pnpm build

Development

pnpm dev          # Watch mode (rebuilds on changes)
pnpm typecheck    # Type check
pnpm lint         # Lint
pnpm test         # Run unit tests in watch mode
pnpm test:run     # Run unit tests once

GitHub Action Bundle

The Action runs from the ncc bundle in dist/action/, which is committed. On PRs from a branch in this repo, the Action Bundle workflow rebuilds it and commits it back for you. On fork and Dependabot PRs, rebuild and commit it yourself:

pnpm build:action
git add dist/action

Releases tag the commit that has this bundle. On stable releases, Craft also moves v0 to that commit. Prereleases leave v0 unchanged. See specs/release-process.md.

CI rebuilds the bundle and fails when the committed files differ.

Testing Locally

The CLI runs skills against local git changes. Set up your API key and run it:

# Create .env.local (gitignored)
echo 'WARDEN_ANTHROPIC_API_KEY=sk-ant-...' > .env.local

# Run against uncommitted changes
pnpm cli run

# Run against recent commits
pnpm cli run --base HEAD~3

# Run against a branch
pnpm cli run --base origin/main

# Run a specific skill
pnpm cli run --skill security-review

# JSON output
pnpm cli run --json

Project Structure

packages/
├── warden/       # @sentry/warden package
│   └── src/
│       ├── action/    # GitHub Action entry point
│       ├── cli/       # Local CLI
│       ├── config/    # Config loading (warden.toml)
│       ├── skills/    # Built-in skills
│       ├── triggers/  # Trigger matching logic
│       └── types/     # Type definitions
├── docs/         # Docs site
└── evals/        # Eval runner, scenarios, and fixtures