@sentry/warden 0.0.0

package/.claude/skills/warden-skill/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: warden-skill
+description: Guide for using Warden CLI locally to analyze code changes. Use when running warden commands, configuring warden.toml, creating custom skills, understanding triggers, or troubleshooting analysis issues. Triggers on "run warden", "warden config", "warden.toml", "create warden skill", "add trigger", or any Warden-related local development task.
+---
+
+# Warden Usage
+
+Warden is an event-driven AI agent that analyzes code changes and executes configurable skills to produce structured reports with findings.
+
+## Quick Start
+
+```bash
+# Set API key
+export WARDEN_ANTHROPIC_API_KEY=sk-ant-...
+
+# Analyze uncommitted changes (uses warden.toml triggers)
+warden
+
+# Run specific skill on uncommitted changes
+warden --skill find-bugs
+
+# Analyze specific files
+warden src/auth.ts src/database.ts
+
+# Analyze changes from git ref
+warden main..HEAD
+warden HEAD~3
+```
+
+## CLI Reference
+
+```
+warden [command] [targets...] [options]
+```
+
+**Commands:**
+- `(default)` - Run analysis
+- `init` - Initialize warden.toml and GitHub workflow
+- `add [skill]` - Add skill trigger to warden.toml
+- `sync [repo]` - Update cached remote skills to latest
+- `setup-app` - Create GitHub App via manifest flow
+
+**Targets:**
+- `<files>` - Specific files (e.g., `src/auth.ts`)
+- `<glob>` - Pattern match (e.g., `src/**/*.ts`)
+- `<git-ref>` - Git range (e.g., `main..HEAD`, `HEAD~3`)
+- `(none)` - Uncommitted changes
+
+**Key Options:**
+| Option | Description |
+|--------|-------------|
+| `--skill <name>` | Run only this skill |
+| `--config <path>` | Path to warden.toml (default: ./warden.toml) |
+| `-m, --model <model>` | Model to use |
+| `--json` | Output as JSON |
+| `-o, --output <path>` | Write output to JSONL file |
+| `--fail-on <severity>` | Exit 1 if findings >= severity |
+| `--comment-on <severity>` | Show findings >= severity |
+| `--fix` | Auto-apply suggested fixes |
+| `--parallel <n>` | Concurrent executions (default: 4) |
+| `--offline` | Use cached remote skills only |
+| `-q, --quiet` | Errors and summary only |
+| `-v, --verbose` | Show real-time findings |
+| `-vv` | Debug info (tokens, latency) |
+
+**Severity levels:** `critical`, `high`, `medium`, `low`, `info`, `off`
+
+## Configuration (warden.toml)
+
+See [references/config-schema.md](references/config-schema.md) for complete schema.
+
+**Minimal example:**
+
+```toml
+version = 1
+
+[defaults]
+model = "claude-sonnet-4-20250514"
+
+[[triggers]]
+name = "find-bugs"
+event = "pull_request"
+actions = ["opened", "synchronize"]
+skill = "find-bugs"
+
+[triggers.filters]
+paths = ["src/**/*.ts"]
+```
+
+**With custom output thresholds:**
+
+```toml
+[[triggers]]
+name = "security-strict"
+event = "pull_request"
+actions = ["opened", "synchronize"]
+skill = "security-review"
+
+[triggers.filters]
+paths = ["src/auth/**", "src/payments/**"]
+
+[triggers.output]
+failOn = "critical"
+commentOn = "high"
+maxFindings = 20
+```
+
+## Creating Custom Skills
+
+Skills live in `.warden/skills/`, `.agents/skills/`, or `.claude/skills/`.
+
+**Structure:**
+```
+.warden/skills/my-skill/
+└── SKILL.md
+```
+
+**SKILL.md format:**
+
+```markdown
+---
+name: my-skill
+description: What this skill analyzes
+allowed-tools: Read Grep Glob
+---
+
+[Analysis instructions for the agent]
+
+## What to Look For
+- Specific issue type 1
+- Specific issue type 2
+
+## Output Format
+Report findings with severity, location, and suggested fix.
+```
+
+**Available tools:** `Read`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, `Bash`, `Write`, `Edit`
+
+## Remote Skills
+
+Skills can be fetched from GitHub repositories:
+
+```bash
+# Add a remote skill
+warden add --remote getsentry/skills --skill security-review
+
+# Add with version pinning (recommended for reproducibility)
+warden add --remote getsentry/skills@abc123 --skill security-review
+
+# List skills in a remote repo
+warden add --remote getsentry/skills --list
+
+# Update all unpinned remote skills
+warden sync
+
+# Update specific repo
+warden sync getsentry/skills
+
+# Run with cached skills only (no network)
+warden --offline
+```
+
+**Remote trigger in warden.toml:**
+
+```toml
+[[triggers]]
+name = "security-review"
+event = "pull_request"
+actions = ["opened", "synchronize"]
+skill = "security-review"
+remote = "getsentry/skills@abc123"
+```
+
+**Cache location:** `~/.local/warden/skills/` (override with `WARDEN_STATE_DIR`)
+
+**Cache TTL:** 24 hours for unpinned refs (override with `WARDEN_SKILL_CACHE_TTL` in seconds)
+
+**Inline skill in warden.toml:**
+
+```toml
+[[skills]]
+name = "custom-check"
+description = "Check for TODO comments"
+prompt = """
+Find TODO comments that have been in the code for too long.
+Report as low severity findings.
+"""
+
+[skills.tools]
+allowed = ["Read", "Grep", "Glob"]
+```
+
+## Built-in Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `find-bugs` | Logical/functional bugs, null handling, async issues |
+| `security-review` | Injection, auth, CSRF, crypto, race conditions |
+| `code-simplifier` | Readability, consistency, redundancy removal |
+| `performance-review` | N+1 queries, blocking I/O, memory leaks |
+
+## Common Patterns
+
+**Strict security on critical files:**
+```toml
+[[triggers]]
+name = "auth-security"
+event = "pull_request"
+actions = ["opened", "synchronize"]
+skill = "security-review"
+model = "claude-opus-4-20250514"
+maxTurns = 100
+
+[triggers.filters]
+paths = ["src/auth/**", "src/payments/**"]
+
+[triggers.output]
+failOn = "critical"
+```
+
+**Skip test files:**
+```toml
+[triggers.filters]
+paths = ["src/**/*.ts"]
+ignorePaths = ["**/*.test.ts", "**/*.spec.ts"]
+```
+
+**Whole-file analysis for configs:**
+```toml
+[defaults.chunking.filePatterns]
+pattern = "*.config.*"
+mode = "whole-file"
+```
+
+## Troubleshooting
+
+**No findings reported:**
+- Check `--comment-on` threshold (default shows all)
+- Verify skill matches file types in `filters.paths`
+- Use `-v` to see which files are being analyzed
+
+**Files being skipped:**
+- Built-in skip patterns: lock files, minified, `node_modules/`, `dist/`
+- Check `ignorePaths` in config
+- Use `-vv` to see skip reasons
+
+**Token/cost issues:**
+- Reduce `maxTurns` (default: 50)
+- Use chunking settings to control chunk size
+- Filter to relevant files with `paths`

package/.claude/skills/warden-skill/references/config-schema.md

@@ -0,0 +1,133 @@
+# warden.toml Configuration Schema
+
+## Top-Level Structure
+
+```toml
+version = 1                    # Required, must be 1
+
+[defaults]                     # Optional, inherited by all triggers
+[[triggers]]                   # Required, array of trigger configs
+[[skills]]                     # Optional, inline skill definitions
+```
+
+## Defaults Section
+
+```toml
+[defaults]
+model = "claude-sonnet-4-20250514"    # Default model
+maxTurns = 50                         # Max agentic turns per hunk
+defaultBranch = "main"                # Base branch for comparisons
+
+[defaults.output]
+failOn = "high"                # Exit 1 if findings >= this severity
+commentOn = "medium"           # Show findings >= this severity
+maxFindings = 50               # Max findings to report (0 = unlimited)
+commentOnSuccess = false       # Post comment even with no findings
+
+[defaults.filters]
+paths = ["src/**/*.ts"]        # Include only matching files
+ignorePaths = ["*.test.ts"]    # Exclude matching files
+
+[defaults.chunking]
+enabled = true                 # Enable hunk-based chunking
+
+[defaults.chunking.coalesce]
+enabled = true                 # Merge nearby hunks
+maxGapLines = 30               # Lines between hunks to merge
+maxChunkSize = 8000            # Max chars per chunk
+
+[[defaults.chunking.filePatterns]]
+pattern = "*.config.*"         # Glob pattern
+mode = "whole-file"            # per-hunk | whole-file | skip
+```
+
+## Triggers Section
+
+```toml
+[[triggers]]
+name = "trigger-name"          # Required, unique identifier
+event = "pull_request"         # Required: pull_request | issues | issue_comment | schedule
+actions = ["opened", "synchronize"]  # Required for non-schedule events
+skill = "find-bugs"            # Required, skill name or path
+remote = "owner/repo@sha"      # Optional, fetch skill from GitHub repo
+
+# Optional overrides (inherit from defaults if not set)
+model = "claude-opus-4-20250514"
+maxTurns = 100
+
+[triggers.filters]
+paths = ["src/**"]
+ignorePaths = ["**/*.test.ts"]
+
+[triggers.output]
+failOn = "critical"
+commentOn = "high"
+maxFindings = 20
+commentOnSuccess = true
+
+# Schedule-specific (only for event = "schedule")
+[triggers.schedule]
+issueTitle = "Daily Security Review"   # GitHub issue title for tracking
+createFixPR = true                     # Create PR with fixes
+fixBranchPrefix = "security-fix"       # Branch name prefix
+```
+
+**Event types:**
+- `pull_request` - Triggers on PR events
+- `issues` - Triggers on issue events
+- `issue_comment` - Triggers on issue/PR comments
+- `schedule` - Triggers on cron schedule (GitHub Action)
+
+**Actions (for non-schedule):**
+- `opened`, `synchronize`, `reopened`, `closed`
+
+## Skills Section (Inline Skills)
+
+```toml
+[[skills]]
+name = "custom-skill"
+description = "What this skill checks"
+prompt = """
+Analysis instructions here.
+Look for specific issues.
+"""
+
+[skills.tools]
+allowed = ["Read", "Grep", "Glob"]     # Whitelist tools
+denied = ["Write", "Edit", "Bash"]     # Blacklist tools (optional)
+```
+
+## Severity Values
+
+Used in `failOn` and `commentOn`:
+- `critical` - Most severe
+- `high`
+- `medium`
+- `low`
+- `info` - Least severe
+- `off` - Disable threshold
+
+## Built-in Skip Patterns
+
+Always skipped (cannot be overridden):
+- Package locks: `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `Cargo.lock`, etc.
+- Minified files: `**/*.min.js`, `**/*.min.css`
+- Build artifacts: `dist/`, `build/`, `node_modules/`, `.next/`, `__pycache__/`
+- Generated code: `*.generated.*`, `*.g.ts`, `__generated__/`
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `WARDEN_ANTHROPIC_API_KEY` | Claude API key (required) |
+| `WARDEN_MODEL` | Default model (lowest priority) |
+| `WARDEN_STATE_DIR` | Override cache location (default: `~/.local/warden`) |
+| `WARDEN_SKILL_CACHE_TTL` | Cache TTL in seconds for unpinned remotes (default: 86400) |
+
+## Model Precedence (highest to lowest)
+
+1. Trigger-level `model`
+2. `[defaults]` `model`
+3. CLI `--model` flag
+4. `WARDEN_MODEL` env var
+5. SDK default

package/.dex/config.toml

@@ -0,0 +1,2 @@
+[sync.github]
+enabled = true

package/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm typecheck
+      - run: pnpm lint
+      - run: pnpm test
+      - run: pnpm build
+      - run: pnpm build:action

package/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: pnpm build:action
+
+      - name: Get version info
+        id: version
+        run: |
+          echo "tag=$GITHUB_REF_NAME" >> $GITHUB_OUTPUT
+          echo "major=${GITHUB_REF_NAME%%.*}" >> $GITHUB_OUTPUT
+
+      - name: Commit dist/action to tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -f dist/action/
+          git commit -m "Build action for ${{ steps.version.outputs.tag }}"
+          git tag -f ${{ steps.version.outputs.tag }}
+          git push -f origin ${{ steps.version.outputs.tag }}
+
+      - name: Update major version tag
+        run: |
+          git tag -f ${{ steps.version.outputs.major }}
+          git push -f origin ${{ steps.version.outputs.major }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.version.outputs.tag }}
+          generate_release_notes: true

package/.github/workflows/warden.yml

@@ -0,0 +1,40 @@
+name: Warden
+
+permissions:
+  contents: read
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    env:
+      WARDEN_ANTHROPIC_API_KEY: ${{ secrets.WARDEN_ANTHROPIC_API_KEY }}
+      WARDEN_MODEL: ${{ secrets.WARDEN_MODEL }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: pnpm build:action
+
+      - uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ secrets.WARDEN_APP_ID }}
+          private-key: ${{ secrets.WARDEN_PRIVATE_KEY }}
+
+      - uses: ./
+        with:
+          github-token: ${{ steps.app-token.outputs.token }}

package/AGENTS.md

@@ -0,0 +1,89 @@
+# Agent Instructions
+
+## Package Manager
+
+Use **pnpm**: `pnpm install`, `pnpm build`, `pnpm test`
+
+## Commit Attribution
+
+AI commits MUST include:
+
+```
+Co-Authored-By: <model name> <noreply@anthropic.com>
+```
+
+Example: `Co-Authored-By: Claude Sonnet 4 <noreply@anthropic.com>`
+
+## Architecture
+
+```
+src/
+├── index.ts           # Library entry point
+├── types/             # Zod schemas and types
+├── config/            # Config loading (warden.toml)
+├── triggers/          # Event trigger matching
+├── event/             # GitHub event parsing
+├── diff/              # Diff parsing and context
+├── output/            # Report rendering
+├── skills/            # Skill discovery and loading
+├── sdk/               # Claude Code SDK runner
+├── cli/               # CLI entry and commands
+│   └── output/        # CLI output formatting
+├── action/            # GitHub Action entry
+├── utils/             # Shared utilities
+└── examples/          # Example configurations
+```
+
+## Key Conventions
+
+- TypeScript strict mode
+- Zod for runtime validation
+- ESM modules (`"type": "module"`)
+- Vitest for testing
+
+## TypeScript Exports
+
+Use `export type` for type-only exports. This is required for Bun compatibility:
+
+```ts
+// Good
+export type { SkillReport } from "./types/index.js";
+export { runSkill } from "./sdk/runner.js";
+
+// Bad - fails in Bun
+export { SkillReport, runSkill } from "./types/index.js";
+```
+
+## Testing
+
+**Always reference `/testing-guidelines` when writing tests.** Key principles:
+
+- Mock external services, use sanitized real-world fixtures
+- Prefer integration tests over unit tests
+- Always add regression tests for bugs
+- Cover every user entry point with at least a happy-path test
+- Co-locate tests with source (`foo.ts` → `foo.test.ts`)
+
+## Verifying Changes
+
+```bash
+pnpm lint && pnpm build && pnpm test
+```
+
+## Task Management
+
+Use `/dex` to break down complex work, track progress across sessions, and coordinate multi-step implementations.
+
+## Skills Policy
+
+Skills define **what to look for**, not how to respond to findings:
+
+- When Warden reports findings, fix the code. Don't modify skills to suppress results
+- Skills should only change to improve detection accuracy, not to reduce reported findings
+- Each skill owns its domain expertise; severity definitions are intentionally domain-agnostic
+
+## Voice
+
+Warden watches over your code. Not "AI code reviewer" or similar.
+
+Keep it brief, dry, and slightly ominous. Think security guard who's seen everything. Professional but with personality. No fluff, no hype, no em-dashes.

package/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to Warden
+
+## Prerequisites
+
+- Node.js >= 20.0.0
+- pnpm (install via `npm install -g pnpm`)
+- An Anthropic API key for running skills
+
+## Setup
+
+```bash
+pnpm install
+pnpm build
+```
+
+## Development
+
+```bash
+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
+```
+
+## Testing Locally
+
+The CLI runs skills against local git changes. Set up your API key and run it:
+
+```bash
+# 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
+
+```
+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
+```