@sentry/warden 0.0.0

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2025 Functional Software, Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,43 @@
+<p align="center">
+  <img src="assets/warden-icon-purple.svg" alt="Warden" width="128" height="128">
+</p>
+
+# warden
+
+Your code is under new management. Agents that review your code - locally or on every PR - using the Skills you already know and love.
+
+## Why Warden?
+
+**Skills, not prompts.** Define analysis once, run it anywhere. Bootstrap your environment with skills from conventional directories (`.warden/skills/`, `.agents/skills/`, `.claude/skills/`).
+
+**Two ways to run.** CLI catches issues before you push. GitHub Action reviews every PR automatically.
+
+**GitHub-native.** Findings appear as inline PR comments with suggested fixes.
+
+## Quick Start
+
+```bash
+# Initialize warden in your repository
+npx warden init
+
+# Run on uncommitted changes
+# Uses Claude Code subscription if logged in, or set WARDEN_ANTHROPIC_API_KEY
+npx warden
+
+# Fix issues automatically
+npx warden --fix
+```
+
+**[Read the full documentation →](https://warden.sentry.dev/)**
+
+## Contributing
+
+```bash
+git clone git@github.com:getsentry/warden.git
+cd warden
+pnpm install && pnpm build
+```
+
+## License
+
+FSL-1.1-ALv2

package/SPEC.md

@@ -0,0 +1,263 @@
+# Warden Spec
+
+## Overview
+
+Warden is an event-driven agent that reacts to GitHub events (Pull Requests, Issues, etc.) and executes configured skills using Claude Code SDK to produce structured reports. These reports are then translated into GitHub actions like inline comments, suggested changes, or status checks.
+
+**Key Decisions:**
+- **Runtime**: GitHub Action (primary), with Cloudflare/Vercel webhook option
+- **LLM Execution**: Claude Code SDK (spawns agents per skill)
+- **Configuration**: In-repo `warden.yaml` with optional central defaults
+- **Tech Stack**: TypeScript/Node.js
+
+## Core Architecture
+
+```
+┌─────────────┐     ┌──────────────┐     ┌─────────────┐     ┌──────────────┐
+│   Trigger   │────▶│    Config    │────▶│  Claude     │────▶│    Output    │
+│ (GH Action  │     │   Resolver   │     │  Code SDK   │     │   Renderer   │
+│ or Webhook) │     │              │     │   Agent     │     │              │
+└─────────────┘     └──────────────┘     └─────────────┘     └──────────────┘
+                           │                    │                    │
+                           ▼                    ▼                    ▼
+                    ┌──────────────┐     ┌─────────────┐     ┌──────────────┐
+                    │  warden.yaml │     │   Skills    │     │   GitHub     │
+                    │  (in-repo)   │     │  (prompts)  │     │     API      │
+                    └──────────────┘     └─────────────┘     └──────────────┘
+```
+
+## Components
+
+### 1. Event Ingestion
+
+Receives GitHub webhooks and normalizes them into internal event types.
+
+**Supported Events:**
+- `pull_request` (opened, synchronize, reopened, closed)
+- `issues` (opened, edited, closed)
+- `issue_comment` (created, edited)
+- `pull_request_review` (submitted)
+- `pull_request_review_comment` (created)
+
+### 2. Configuration System
+
+Maps events to skills via declarative configuration.
+
+```yaml
+# Example: warden.yaml
+version: 1
+
+triggers:
+  - name: "Security Review on PR"
+    event: pull_request
+    actions: [opened, synchronize]
+    skills:
+      - identify-security-vuln
+      - check-dependencies
+
+  - name: "Code Review"
+    event: pull_request
+    actions: [opened]
+    skills:
+      - code-review
+    filters:
+      paths:
+        - "src/**/*.ts"
+```
+
+### 3. Skill System
+
+Skills are defined as configurations that get executed via Claude Code SDK. Each skill is essentially:
+- A system prompt defining the agent's purpose
+- Tool restrictions (what the agent can/cannot do)
+- Output schema for structured results
+
+**Skill Definition:**
+```yaml
+# skills/security-review.yaml
+name: security-review
+description: Identify security vulnerabilities in code changes
+
+prompt: |
+  You are a security reviewer. Analyze the PR diff for:
+  - Injection vulnerabilities (SQL, XSS, command injection)
+  - Authentication/authorization issues
+  - Secrets or credentials in code
+  - Insecure dependencies
+
+  Return findings in the specified JSON schema.
+
+tools:
+  allowed:
+    - Read
+    - Grep
+    - Glob
+    - WebFetch  # for checking CVE databases
+  denied:
+    - Write
+    - Edit
+    - Bash
+
+output_schema: SkillReport  # references shared schema
+```
+
+**Example Skills:**
+- `security-review` - Scan for security vulnerabilities
+- `code-review` - General code quality feedback
+- `dependency-check` - Check for outdated/vulnerable deps
+- `test-coverage` - Analyze if new code has tests
+- `documentation-check` - Ensure public APIs are documented
+
+**Skills:**
+Users define skills in conventional directories: `.warden/skills/`, `.agents/skills/`, or `.claude/skills/`
+
+### 3a. Internal Meta-Skills (for development)
+
+Warden includes internal skills (in `.claude/skills/`) that help **design and validate new skills**. These are not user-facing skills that run on PRs - they're development aids.
+
+**skill-writer** - Helps create correct skill definitions:
+- Takes a natural language description of what the skill should do
+- Generates a valid skill YAML with proper prompt engineering
+- Ensures output schema compliance
+- Suggests appropriate tool restrictions
+
+This mirrors Claude's own skill-writer pattern and helps bootstrap new skills correctly.
+
+### 4. Skill Report (Structured Output)
+
+```typescript
+interface SkillReport {
+  skill: string;
+  summary: string;
+  findings: Finding[];
+  metadata?: Record<string, unknown>;
+}
+
+interface Finding {
+  id: string;
+  severity: 'critical' | 'high' | 'medium' | 'low' | 'info';
+  title: string;
+  description: string;
+  location?: {
+    path: string;
+    startLine: number;
+    endLine?: number;
+  };
+  suggestedFix?: {
+    description: string;
+    diff: string;  // unified diff format
+  };
+}
+```
+
+### 5. Output Renderer
+
+Translates SkillReport into GitHub API calls.
+
+**Output Types:**
+- **PR Review Comment**: Inline comment on specific lines
+- **PR Review**: Overall review with approve/request-changes/comment
+- **Suggested Change**: GitHub's suggestion block format
+- **Issue Comment**: General comment on issue/PR
+- **Status Check**: Pass/fail status with details URL
+
+---
+
+## Trigger Mechanisms
+
+### Option A: GitHub Action (Recommended for MVP)
+
+```yaml
+# .github/workflows/warden.yml
+name: Warden
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  issues:
+    types: [opened]
+
+jobs:
+  warden:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: anthropics/warden-action@v1
+        with:
+          anthropic-api-key: ${{ secrets.WARDEN_ANTHROPIC_API_KEY }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+**Pros:** No infrastructure to maintain, familiar to users, runs in repo context
+**Cons:** Cold start latency, limited to GitHub Action runtime constraints
+
+### Option B: Webhook Service (Cloudflare/Vercel)
+
+For orgs wanting faster response times or central management.
+
+```
+GitHub App webhook → Cloudflare Worker → Clone repo → Run Warden → Post results
+```
+
+---
+
+## Claude Code SDK Integration
+
+Warden uses the Claude Code SDK to spawn agents for each skill:
+
+```typescript
+import { ClaudeCode } from '@anthropic-ai/claude-code';
+
+async function runSkill(skill: SkillConfig, context: EventContext): Promise<SkillReport> {
+  const claude = new ClaudeCode({
+    apiKey: process.env.WARDEN_ANTHROPIC_API_KEY,
+  });
+
+  const session = await claude.createSession({
+    systemPrompt: skill.prompt,
+    tools: skill.tools,
+    workingDirectory: context.repoPath,
+  });
+
+  // Provide context about the PR/issue
+  const result = await session.run(`
+    Analyze this pull request:
+    - Title: ${context.pr.title}
+    - Description: ${context.pr.body}
+    - Files changed: ${context.pr.files.map(f => f.filename).join(', ')}
+
+    The diff is available in the working directory.
+    Return your findings as JSON matching the SkillReport schema.
+  `);
+
+  return parseSkillReport(result);
+}
+```
+
+---
+
+## MVP Scope
+
+**In Scope:**
+- GitHub Action trigger only (no webhook service yet)
+- `pull_request` events (opened, synchronize)
+- Skills from conventional directories (`.warden/skills/`, `.agents/skills/`, `.claude/skills/`)
+- Internal meta-skill: `skill-writer` (to help design correct skills)
+- Three output types: inline comments, suggested changes, summary comment
+- In-repo `warden.yaml` configuration
+- One-shot analysis (no conversation follow-ups)
+
+**Out of Scope (Future):**
+- Webhook service (Cloudflare/Vercel)
+- Issue events
+- Conversation mode (responding to replies)
+- Additional built-in skills
+- Central/org-level configuration
+- Caching/incremental analysis
+
+---
+
+## Open Questions (for future consideration)
+
+1. **Rate Limiting**: How to handle API rate limits when many PRs open simultaneously?
+2. **Caching**: Should we cache analysis of unchanged files across PR updates?
+3. **Incremental Analysis**: On `synchronize` events, only analyze new commits or full diff?

package/action.yml

@@ -0,0 +1,87 @@
+name: 'Warden'
+description: 'Event-driven agent that analyzes GitHub PRs using Claude Code SDK'
+author: 'Functional Software, Inc.'
+
+branding:
+  icon: 'shield'
+  color: 'purple'
+
+inputs:
+  anthropic-api-key:
+    description: 'Anthropic API key for Claude Code SDK. Can also be provided via WARDEN_ANTHROPIC_API_KEY environment variable.'
+    required: false
+  github-token:
+    description: 'GitHub token for API access (defaults to GITHUB_TOKEN)'
+    required: false
+    default: ${{ github.token }}
+  config-path:
+    description: 'Path to warden.toml config file (relative to repo root)'
+    required: false
+    default: 'warden.toml'
+  fail-on:
+    description: 'Minimum severity level to fail the action (off, critical, high, medium, low, info). Use "off" to never fail.'
+    required: false
+    default: 'high'
+  comment-on:
+    description: 'Minimum severity level to show annotations in code review (off, critical, high, medium, low, info). Use "off" to disable comments.'
+    required: false
+    default: 'medium'
+  max-findings:
+    description: 'Maximum number of findings to report (0 for unlimited)'
+    required: false
+    default: '50'
+  parallel:
+    description: 'Maximum number of concurrent trigger executions'
+    required: false
+    default: '5'
+
+outputs:
+  findings-count:
+    description: 'Total number of findings'
+    value: ${{ steps.warden.outputs.findings-count }}
+  critical-count:
+    description: 'Number of critical severity findings'
+    value: ${{ steps.warden.outputs.critical-count }}
+  high-count:
+    description: 'Number of high severity findings'
+    value: ${{ steps.warden.outputs.high-count }}
+  summary:
+    description: 'Summary of the analysis'
+    value: ${{ steps.warden.outputs.summary }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Install Claude Code CLI
+      shell: bash
+      run: |
+        CLAUDE_CODE_VERSION="2.1.23"
+        echo "Installing Claude Code v${CLAUDE_CODE_VERSION}..."
+        for attempt in 1 2 3; do
+          echo "Installation attempt $attempt..."
+          if curl -fsSL https://claude.ai/install.sh | bash -s -- "$CLAUDE_CODE_VERSION"; then
+            break
+          fi
+          if [ $attempt -eq 3 ]; then
+            echo "Failed to install Claude Code after 3 attempts"
+            exit 1
+          fi
+          echo "Installation failed, retrying..."
+          sleep 5
+        done
+        echo "Claude Code installed successfully"
+        echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+    - name: Run Warden
+      id: warden
+      shell: bash
+      env:
+        INPUT_ANTHROPIC_API_KEY: ${{ inputs.anthropic-api-key }}
+        INPUT_GITHUB_TOKEN: ${{ inputs.github-token }}
+        INPUT_CONFIG_PATH: ${{ inputs.config-path }}
+        INPUT_FAIL_ON: ${{ inputs.fail-on }}
+        INPUT_COMMENT_ON: ${{ inputs.comment-on }}
+        INPUT_MAX_FINDINGS: ${{ inputs.max-findings }}
+        INPUT_PARALLEL: ${{ inputs.parallel }}
+        CLAUDE_CODE_PATH: ${{ env.HOME }}/.local/bin/claude
+      run: node ${{ github.action_path }}/dist/action/index.js

package/assets/warden-icon-bw.svg

@@ -0,0 +1,5 @@
+<svg width="64" height="64" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="24" height="24" fill="white"/>
+<path d="M14.2666 4.9061C15.1564 4.09409 16.5921 4.60917 16.7627 5.80162L18.1123 15.2519C18.9476 14.5758 19.6675 14.156 20.2706 13.9423C20.9583 13.6988 21.61 13.6893 22.0606 14.0459C22.5331 14.4202 22.576 15.0232 22.4131 15.5224C22.2471 16.0308 21.8525 16.5326 21.2774 16.916C20.2382 17.6088 19.1848 18.1368 17.7432 18.4863C16.3131 18.833 14.518 19 12 19C9.48202 19 7.68685 18.833 6.25679 18.4863C4.81521 18.1368 3.76183 17.6088 2.72259 16.916C2.14753 16.5326 1.75289 16.0308 1.58684 15.5224C1.42401 15.0233 1.46701 14.4202 1.93938 14.0459C2.38997 13.6893 3.04168 13.6988 3.72943 13.9423C4.33238 14.1559 5.05163 14.5761 5.88667 15.2519L7.23727 5.80162C7.40784 4.60919 8.84362 4.09419 9.73338 4.9061L11.6631 6.66686C11.854 6.84121 12.146 6.84121 12.3369 6.66686L14.2666 4.9061Z" fill="#181225"/>
+<path d="M12 8L13.1226 11.1094H16.7553L13.8164 13.0312L14.9389 16.1406L12 14.2188L9.06107 16.1406L10.1836 13.0312L7.24472 11.1094H10.8774L12 8Z" fill="white"/>
+</svg>

package/assets/warden-icon-purple.svg

@@ -0,0 +1,5 @@
+<svg width="64" height="64" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="24" height="24" fill="#7553FF"/>
+<path d="M14.2666 4.9061C15.1564 4.09409 16.5921 4.60917 16.7627 5.80162L18.1123 15.2519C18.9476 14.5758 19.6675 14.156 20.2706 13.9423C20.9583 13.6988 21.61 13.6893 22.0606 14.0459C22.5331 14.4202 22.576 15.0232 22.4131 15.5224C22.2471 16.0308 21.8525 16.5326 21.2774 16.916C20.2382 17.6088 19.1848 18.1368 17.7432 18.4863C16.3131 18.833 14.518 19 12 19C9.48202 19 7.68685 18.833 6.25679 18.4863C4.81521 18.1368 3.76183 17.6088 2.72259 16.916C2.14753 16.5326 1.75289 16.0308 1.58684 15.5224C1.42401 15.0233 1.46701 14.4202 1.93938 14.0459C2.38997 13.6893 3.04168 13.6988 3.72943 13.9423C4.33238 14.1559 5.05163 14.5761 5.88667 15.2519L7.23727 5.80162C7.40784 4.60919 8.84362 4.09419 9.73338 4.9061L11.6631 6.66686C11.854 6.84121 12.146 6.84121 12.3369 6.66686L14.2666 4.9061Z" fill="white"/>
+<path d="M12 8L13.1226 11.1094H16.7553L13.8164 13.0312L14.9389 16.1406L12 14.2188L9.06107 16.1406L10.1836 13.0312L7.24472 11.1094H10.8774L12 8Z" fill="#7553FF"/>
+</svg>

package/docs/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pnpm build:*)",
+      "Bash(git add:*)",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\ndocs: Add remote skills docs, convert tables to definition lists\n\n- Document warden sync command and --repo flag for remote skills\n- Add skill references section explaining resolution order\n- Add --offline flag and WARDEN_SKILL_CACHE_TTL env var\n- Convert all field reference tables to definition lists\n- Update dl/dt/dd styling for monospace keys with purple color\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\ndocs\\(config\\): Remove absolute path example from skill references\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git commit -m \"$\\(cat <<''EOF''\ndocs: Use purple Warden icon for GitHub bot avatar\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")"
+    ]
+  }
+}

package/docs/astro.config.mjs

@@ -0,0 +1,43 @@
+import { defineConfig, fontProviders } from 'astro/config';
+import mdx from '@astrojs/mdx';
+import rehypeAutolinkHeadings from 'rehype-autolink-headings';
+import rehypeSlug from 'rehype-slug';
+
+export default defineConfig({
+  site: 'https://warden.sentry.dev',
+  integrations: [mdx()],
+  markdown: {
+    shikiConfig: {
+      theme: 'vitesse-black',
+    },
+    rehypePlugins: [
+      rehypeSlug,
+      [rehypeAutolinkHeadings, {
+        behavior: 'prepend',
+        properties: { className: ['heading-anchor'] },
+        content: { type: 'text', value: '#' }
+      }],
+    ],
+  },
+  experimental: {
+    fonts: [{
+      name: "Geist Mono",
+      provider: fontProviders.local(),
+      cssVariable: "--font-geist-mono",
+      options: {
+          variants: [
+              {
+                  weight: 400,
+                  style: "normal",
+                  src: ["./node_modules/geist/dist/fonts/geist-mono/GeistMono-Regular.woff2"]
+              },
+              {
+                  weight: 600,
+                  style: "normal",
+                  src: ["./node_modules/geist/dist/fonts/geist-mono/GeistMono-SemiBold.woff2"]
+              }
+          ]
+      }
+    }]
+  }
+});

package/docs/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "dex-docs",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview"
+  },
+  "dependencies": {
+    "@astrojs/mdx": "^4.0.0",
+    "astro": "^5.0.0",
+    "geist": "^1.5.1",
+    "rehype-autolink-headings": "^7.1.0",
+    "rehype-slug": "^6.0.0",
+    "shiki": "^1.0.0",
+    "unist-util-visit": "^5.1.0"
+  }
+}