@sentry/warden 0.4.0 → 0.6.0

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

@@ -0,0 +1,144 @@
+# 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 |
+|-------|---------|
+| `critical` | Must fix before merge |
+| `high` | Should fix before merge |
+| `medium` | Worth reviewing |
+| `low` | Minor improvement |
+| `info` | Informational only |
+| `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 security-review
+warden add --list
+
+# Remote skills
+warden add --remote getsentry/skills --skill security-review
+warden add --remote https://github.com/getsentry/skills --skill security-review
+warden add --remote getsentry/skills@abc123 --skill security-review
+
+# Run analysis
+warden                                  # Skills from warden.toml
+warden src/auth.ts                      # Specific file
+warden src/auth.ts --skill security-review
+warden "src/**/*.ts"                    # Glob pattern
+warden HEAD~3                           # Git changes
+warden HEAD~3 --skill security-review
+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/plugins/warden/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 = "critical"
+reportOn = "high"
+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` - Triggers on local CLI runs
+- `schedule` - Triggers on cron schedule (GitHub Action)
+
+**Actions (for pull_request):**
+- `opened`, `synchronize`, `reopened`, `closed`
+
+## Severity Values
+
+Used in `failOn` and `reportOn`:
+- `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. Skill-level `model`
+2. `[defaults]` `model`
+3. CLI `--model` flag
+4. `WARDEN_MODEL` env var
+5. SDK default

package/plugins/warden/skills/warden/references/configuration.md

@@ -0,0 +1,108 @@
+# Configuration (warden.toml)
+
+See [config-schema.md](config-schema.md) for the complete schema reference.
+
+## Minimal Example
+
+```toml
+version = 1
+
+[defaults]
+model = "claude-sonnet-4-20250514"
+
+[[skills]]
+name = "find-bugs"
+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 and at least one trigger:
+
+```toml
+[[skills]]
+name = "security-review"
+paths = ["src/auth/**", "src/payments/**"]
+failOn = "critical"
+reportOn = "high"
+maxFindings = 20
+
+[[skills.triggers]]
+type = "pull_request"
+actions = ["opened", "synchronize"]
+```
+
+**Trigger types:** `pull_request`, `local`, `schedule`
+
+**Actions (pull_request):** `opened`, `synchronize`, `reopened`, `closed`
+
+## Common Patterns
+
+**Strict security on critical files:**
+```toml
+[[skills]]
+name = "security-review"
+model = "claude-opus-4-20250514"
+maxTurns = 100
+paths = ["src/auth/**", "src/payments/**"]
+failOn = "critical"
+
+[[skills.triggers]]
+type = "pull_request"
+actions = ["opened", "synchronize"]
+```
+
+**Skip test files:**
+```toml
+[[skills]]
+name = "find-bugs"
+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/plugins/warden/skills/warden/references/creating-skills.md

@@ -0,0 +1,85 @@
+# 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):
+
+```
+.warden/skills/{name}/SKILL.md   # Warden-specific (highest priority)
+.agents/skills/{name}/SKILL.md   # Shared agent skills
+.claude/skills/{name}/SKILL.md   # Claude Code skills
+```
+
+## 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 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 skill in warden.toml:**
+
+```toml
+[[skills]]
+name = "security-review"
+remote = "getsentry/skills@abc123"
+
+[[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)