@sentry/warden 0.13.0 → 0.15.0

package/skills/warden/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: warden
+description: Run Warden to analyze code changes before committing. Use when asked to "run warden", "check my changes", "review before commit", "warden config", "warden.toml", "create a warden skill", "add trigger", or any Warden-related local development task.
+---
+
+Run Warden to analyze code changes before committing.
+
+## References
+
+Read the relevant reference when the task requires deeper detail:
+
+| Document | Read When |
+|----------|-----------|
+| `${CLAUDE_SKILL_ROOT}/references/cli-reference.md` | Full option details, per-command flags, examples |
+| `${CLAUDE_SKILL_ROOT}/references/configuration.md` | Editing warden.toml, triggers, patterns, troubleshooting |
+| `${CLAUDE_SKILL_ROOT}/references/config-schema.md` | Exact field names, types, and defaults |
+| `${CLAUDE_SKILL_ROOT}/references/creating-skills.md` | Writing custom skills, remote skills, skill discovery |
+
+## Running Warden
+
+```bash
+# Analyze uncommitted changes (uses warden.toml triggers)
+warden
+
+# Run a specific skill
+warden --skill <skill-name>
+
+# Analyze specific files
+warden src/auth.ts src/database.ts
+
+# Analyze changes from a git ref
+warden main..HEAD
+warden HEAD~3
+
+# Auto-apply suggested fixes
+warden --fix
+
+# Fail on high-severity findings
+warden --fail-on high
+```
+
+Set `WARDEN_ANTHROPIC_API_KEY` or log in via `claude login` before running.
+
+## Pre-Commit Workflow
+
+After making code changes and before committing:
+
+1. Run `warden` to analyze uncommitted changes
+2. Review the findings
+3. Fix issues Warden reports (or use `warden --fix` to auto-apply)
+4. Commit the changes
+
+Run Warden once to validate work. Do not loop re-running Warden on the same changes.
+
+## Reading Output
+
+**Severity levels:**
+- `high` - Must fix before merge
+- `medium` - Worth reviewing
+- `low` - Minor improvement
+
+**Exit codes:** `0` = no findings at or above fail threshold. `1` = findings at or above fail threshold.
+
+**Verbosity:** `-v` shows real-time findings. `-vv` shows debug info (tokens, latency). `-q` shows errors and summary only.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `warden` | Run analysis (default) |
+| `warden init` | Initialize warden.toml and GitHub workflow |
+| `warden add [skill]` | Add skill trigger to warden.toml |
+| `warden sync [remote]` | Update cached remote skills |
+| `warden setup-app` | Create GitHub App via manifest flow |
+
+For full options and flags, read `${CLAUDE_SKILL_ROOT}/references/cli-reference.md`.

package/skills/warden/references/cli-reference.md

@@ -0,0 +1,142 @@
+# CLI Reference
+
+## Usage
+
+```
+warden [command] [targets...] [options]
+```
+
+Analyze code for security issues and code quality.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `(default)` | Run analysis on targets or using warden.toml skills |
+| `init` | Initialize warden.toml and GitHub workflow |
+| `add [skill]` | Add a skill to warden.toml |
+| `sync [remote]` | Update cached remote skills to latest |
+| `setup-app` | Create a GitHub App for Warden via manifest flow |
+
+## Targets
+
+| Target | Description |
+|--------|-------------|
+| `<files>` | Analyze specific files (e.g., `src/auth.ts`) |
+| `<glob>` | Analyze files matching pattern (e.g., `"src/**/*.ts"`) |
+| `<git-ref>` | Analyze changes from git ref (e.g., `HEAD~3`, `main..feature`) |
+| `(none)` | Analyze uncommitted changes using warden.toml skills |
+
+Ambiguous targets (no path separator, no extension) are resolved by checking if a file exists at the path. Use `--git` to force git ref interpretation.
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--skill <name>` | Run only this skill (default: run all built-in skills) |
+| `--config <path>` | Path to warden.toml (default: `./warden.toml`) |
+| `-m, --model <model>` | Model to use (fallback when not set in config) |
+| `--json` | Output results as JSON |
+| `-o, --output <path>` | Write full run output to a JSONL file |
+| `--fail-on <severity>` | Exit with code 1 if findings >= severity |
+| `--report-on <severity>` | Only show findings >= severity in output |
+| `--fix` | Automatically apply all suggested fixes |
+| `--parallel <n>` | Max concurrent skill executions (default: 4) |
+| `--git` | Force ambiguous targets to be treated as git refs |
+| `--offline` | Use cached remote skills without network access |
+| `-q, --quiet` | Errors and final summary only |
+| `-v, --verbose` | Show real-time findings and hunk details |
+| `-vv` | Show debug info (token counts, latencies) |
+| `--debug` | Enable debug output (equivalent to `-vv`) |
+| `--log` | Use log output (no animations, timestamped) |
+| `--color / --no-color` | Override color detection |
+| `-h, --help` | Show help message |
+| `-V, --version` | Show version number |
+
+## Per-Command Options
+
+**Init:**
+| Option | Description |
+|--------|-------------|
+| `-f, --force` | Overwrite existing files |
+
+**Add:**
+| Option | Description |
+|--------|-------------|
+| `--list` | List available skills |
+| `--remote <ref>` | Remote repository (`owner/repo`, URL, or with `@sha`) |
+| `--force` | Bypass skill cache and fetch latest |
+
+**Sync:**
+| Option | Description |
+|--------|-------------|
+| `--remote <ref>` | Specific remote to sync (default: all) |
+
+**Setup-app:**
+| Option | Description |
+|--------|-------------|
+| `--org <name>` | Create under organization (default: personal) |
+| `--port <number>` | Local server port (default: 3000) |
+| `--timeout <sec>` | Callback timeout in seconds (default: 300) |
+| `--name <string>` | Custom app name (default: Warden) |
+| `--no-open` | Print URL instead of opening browser |
+
+## Severity Levels
+
+Used in `--fail-on` and `--report-on`:
+
+| Level | Meaning |
+|-------|---------|
+| `high` | Must fix before merge |
+| `medium` | Worth reviewing |
+| `low` | Minor improvement |
+| `off` | Disable the threshold |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | No findings at or above `--fail-on` threshold |
+| `1` | Findings at or above `--fail-on` threshold |
+
+## Examples
+
+```bash
+# Initialize
+warden init
+
+# Interactive skill selection
+warden add
+warden add <skill-name>
+warden add --list
+
+# Remote skills
+warden add --remote <org>/<repo> --skill <skill-name>
+warden add --remote https://github.com/<org>/<repo> --skill <skill-name>
+warden add --remote <org>/<repo>@<ref> --skill <skill-name>
+
+# Run analysis
+warden                                  # Skills from warden.toml
+warden src/auth.ts                      # Specific file
+warden src/auth.ts --skill <skill-name>
+warden "src/**/*.ts"                    # Glob pattern
+warden HEAD~3                           # Git changes
+warden HEAD~3 --skill <skill-name>
+warden main..HEAD                       # Branch diff
+
+# Output control
+warden --json
+warden --fail-on high
+warden -o results.jsonl
+
+# Fix mode
+warden --fix
+
+# Cached skills only
+warden --offline
+warden sync                             # Update all unpinned remote skills
+
+# GitHub App setup
+warden setup-app
+warden setup-app --org myorg
+```

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

@@ -0,0 +1,111 @@
+# warden.toml Configuration Schema
+
+## Top-Level Structure
+
+```toml
+version = 1                    # Required, must be 1
+
+[defaults]                     # Optional, inherited by all skills
+[[skills]]                     # Required, array of skill configs
+```
+
+## Defaults Section
+
+```toml
+[defaults]
+model = "claude-sonnet-4-20250514"    # Default model
+maxTurns = 50                         # Max agentic turns per hunk
+defaultBranch = "main"                # Base branch for comparisons
+failOn = "high"                # Exit 1 if findings >= this severity
+reportOn = "medium"            # Show findings >= this severity
+maxFindings = 50               # Max findings to report (0 = unlimited)
+reportOnSuccess = false        # Post report even with no findings
+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
+```
+
+## Skills Section
+
+```toml
+[[skills]]
+name = "skill-name"            # Required, unique identifier
+remote = "owner/repo@sha"      # Optional, fetch skill from GitHub repo
+paths = ["src/**"]             # Include only matching files
+ignorePaths = ["**/*.test.ts"] # Exclude matching files
+
+# Optional overrides (inherit from defaults if not set)
+model = "claude-opus-4-20250514"
+maxTurns = 100
+failOn = "high"
+reportOn = "medium"
+maxFindings = 20
+reportOnSuccess = true
+
+[[skills.triggers]]
+type = "pull_request"          # Required: pull_request | local | schedule
+actions = ["opened", "synchronize"]  # Required for pull_request
+
+# Schedule-specific (only for type = "schedule")
+[[skills.triggers]]
+type = "schedule"
+
+[skills.triggers.schedule]
+issueTitle = "Daily Security Review"   # GitHub issue title for tracking
+createFixPR = true                     # Create PR with fixes
+fixBranchPrefix = "security-fix"       # Branch name prefix
+```
+
+**Trigger types:**
+- `pull_request` - Triggers on PR events
+- `local` - Local CLI only (will not run in CI)
+- `schedule` - Cron schedule (GitHub Action only)
+
+All skills run locally regardless of trigger type. Skills with no triggers run everywhere (wildcard). Use `type = "local"` for skills that should *only* run locally.
+
+**Actions (for pull_request):**
+- `opened`, `synchronize`, `reopened`, `closed`
+
+## Severity Values
+
+Used in `failOn` and `reportOn`:
+- `high` - Must fix before merge
+- `medium` - Worth reviewing
+- `low` - Minor improvement
+- `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. Skill-level `model`
+2. `[defaults]` `model`
+3. CLI `--model` flag
+4. `WARDEN_MODEL` env var
+5. SDK default

package/skills/warden/references/configuration.md

@@ -0,0 +1,110 @@
+# Configuration (warden.toml)
+
+See [config-schema.md](config-schema.md) for the complete schema reference.
+
+## Minimal Example
+
+The `name` field references a skill you've created (via `warden add`) or defined in `.agents/skills/<name>/SKILL.md`. Use that same name everywhere — in config, CLI flags, and triggers.
+
+```toml
+version = 1
+
+[defaults]
+model = "claude-sonnet-4-20250514"
+
+[[skills]]
+name = "my-skill"           # matches .agents/skills/my-skill/SKILL.md
+paths = ["src/**/*.ts"]
+
+[[skills.triggers]]
+type = "pull_request"
+actions = ["opened", "synchronize"]
+```
+
+## Skill Configuration
+
+Skills define what to analyze and when. Each skill requires a name. Triggers are optional — skills with no triggers run everywhere (PR, local, schedule). All skills run locally regardless of trigger type.
+
+```toml
+[[skills]]
+name = "my-skill"
+paths = ["src/auth/**", "src/payments/**"]
+failOn = "high"
+reportOn = "medium"
+maxFindings = 20
+
+[[skills.triggers]]
+type = "pull_request"
+actions = ["opened", "synchronize"]
+```
+
+**Trigger types:** `pull_request`, `local` (local-only), `schedule` (CI-only)
+
+**Actions (pull_request):** `opened`, `synchronize`, `reopened`, `closed`
+
+## Common Patterns
+
+**Strict checks on critical files:**
+```toml
+[[skills]]
+name = "my-skill"
+model = "claude-opus-4-20250514"
+maxTurns = 100
+paths = ["src/auth/**", "src/payments/**"]
+failOn = "high"
+
+[[skills.triggers]]
+type = "pull_request"
+actions = ["opened", "synchronize"]
+```
+
+**Skip test files:**
+```toml
+[[skills]]
+name = "my-skill"
+paths = ["src/**/*.ts"]
+ignorePaths = ["**/*.test.ts", "**/*.spec.ts"]
+```
+
+**Whole-file analysis for configs:**
+```toml
+[defaults.chunking.filePatterns]
+pattern = "*.config.*"
+mode = "whole-file"
+```
+
+## Model Precedence
+
+From highest to lowest priority:
+
+1. Skill-level `model`
+2. `[defaults]` `model`
+3. CLI `--model` flag
+4. `WARDEN_MODEL` env var
+5. SDK default
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `WARDEN_ANTHROPIC_API_KEY` | Claude API key (required unless using Claude Code subscription) |
+| `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) |
+
+## Troubleshooting
+
+**No findings reported:**
+- Check `--report-on` threshold (default shows all)
+- Verify skill matches file types in `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/skills/warden/references/creating-skills.md

@@ -0,0 +1,84 @@
+# Creating Skills
+
+Skills are markdown files that tell Warden what to look for. They follow the [agentskills.io](https://agentskills.io) specification.
+
+## Skill Discovery
+
+Warden searches these directories in order (first match wins):
+
+```
+.agents/skills/{name}/SKILL.md   # Primary (recommended)
+.claude/skills/{name}/SKILL.md   # Backup (Claude Code convention)
+```
+
+## 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`
+
+Most review skills only need `Read`, `Grep`, and `Glob` for exploring context.
+
+## Writing Checklist
+
+- One skill, one concern ("security review" not "code quality")
+- Clear criteria for what counts as an issue and at what severity
+- Actionable findings that include how to fix
+- Examples of good and bad code where helpful
+
+## Remote Skills
+
+Skills can be fetched from GitHub repositories:
+
+```bash
+# Add a remote skill
+warden add --remote <org>/<repo> --skill <skill-name>
+
+# Add with version pinning (recommended for reproducibility)
+warden add --remote <org>/<repo>@<ref> --skill <skill-name>
+
+# List skills in a remote repo
+warden add --remote <org>/<repo> --list
+
+# Update all unpinned remote skills
+warden sync
+
+# Update specific repo
+warden sync <org>/<repo>
+
+# Run with cached skills only (no network)
+warden --offline
+```
+
+**Remote skill in warden.toml:**
+
+```toml
+[[skills]]
+name = "my-skill"
+remote = "<org>/<repo>@<ref>"
+
+[[skills.triggers]]
+type = "pull_request"
+actions = ["opened", "synchronize"]
+```
+
+**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)