@sentry/warden 0.0.0

package/docs/src/pages/guide.astro

@@ -0,0 +1,449 @@
+---
+import Base from '../layouts/Base.astro';
+import Terminal from '../components/Terminal.astro';
+import { Code } from 'astro:components';
+
+const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+---
+
+<Base title="Guide" description="How to use Warden to watch over your code">
+  <h1>Guide</h1>
+
+  <p>Warden watches over your code by running <strong>skills</strong> against your changes. Skills are prompts that define what to look for: security vulnerabilities, API design issues, performance problems, or anything else you want consistent coverage on.</p>
+
+  <nav class="toc">
+    <details open>
+      <summary>On this page</summary>
+      <ul>
+        <li><a href="#the-core-idea">The Core Idea</a></li>
+        <li><a href="#when-to-use-warden">When to Use Warden</a></li>
+        <li><a href="#local-development">Local Development</a></li>
+        <li><a href="#creating-skills">Creating Skills</a></li>
+        <li><a href="#adding-skills">Adding Skills</a></li>
+        <li><a href="#pull-request-reviews">Pull Request Reviews</a></li>
+        <li><a href="#github-app">GitHub App (Optional)</a></li>
+        <li><a href="#tips">Tips</a></li>
+      </ul>
+    </details>
+  </nav>
+
+  <h2 id="the-core-idea">The Core Idea</h2>
+
+  <p>Every time you run Warden, it:</p>
+  <ol>
+    <li>Identifies what changed (files, hunks, or entire directories)</li>
+    <li>Matches changes against configured triggers</li>
+    <li>Runs the appropriate skills against matching code</li>
+    <li>Reports findings with severity, location, and optional fixes</li>
+  </ol>
+
+  <p>Skills follow the <a href="https://agentskills.io">agentskills.io</a> specification -they're markdown files with a prompt that tells the AI what to look for. You can use community skills, write your own, or combine both.</p>
+
+  <p>Warden works in two contexts:</p>
+  <ul>
+    <li><strong>Locally</strong>  - Review changes before you push, get instant feedback</li>
+    <li><strong>In CI</strong>  - Automatically review pull requests, post findings as comments</li>
+  </ul>
+
+  <h2 id="when-to-use-warden">When to Use Warden</h2>
+
+  <p><strong>Use Warden when:</strong></p>
+  <ul>
+    <li>You want consistent code review coverage across your team</li>
+    <li>You need specialized reviews that human reviewers might miss (security, API contracts, accessibility)</li>
+    <li>You want to catch issues before human review starts</li>
+    <li>You're enforcing patterns or conventions specific to your codebase</li>
+  </ul>
+
+  <p><strong>Skip Warden when:</strong></p>
+  <ul>
+    <li>Quick typo or formatting fixes</li>
+    <li>Documentation-only changes (unless you have a docs skill)</li>
+    <li>Generated code or vendored dependencies</li>
+  </ul>
+
+  <h2 id="local-development">Local Development</h2>
+
+  <p>Running Warden locally is the fastest way to get value. You get feedback before pushing, while the code is fresh in your mind.</p>
+
+  <h3>Authentication</h3>
+
+  <p>Warden uses your Claude Code subscription if you're logged in. Otherwise, set an API key:</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`# Option 1: Claude Code subscription (if logged in)
+claude login
+
+# Option 2: API key
+export WARDEN_ANTHROPIC_API_KEY=sk-ant-...`}
+      lang="bash"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <p>Get an API key from <a href="https://console.anthropic.com/">console.anthropic.com</a>. CI/CD environments require an API key.</p>
+
+  <h3>Review Uncommitted Changes</h3>
+
+  <p>Run Warden with no arguments to review your working directory:</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`warden`}
+      lang="bash"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <p>Warden analyzes staged and unstaged changes, running any skills that match via your configured triggers.</p>
+
+  <h3>Review Before Pushing</h3>
+
+  <p>Review all commits on your branch that aren't on main:</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`warden main..HEAD`}
+      lang="bash"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <p>This catches everything you're about to push.</p>
+
+  <h3>Run a Specific Skill</h3>
+
+  <p>Skip trigger matching and run one skill directly:</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`warden --skill security-review`}
+      lang="bash"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <h3>Auto-Fix Issues</h3>
+
+  <p>Let Warden apply suggested fixes interactively:</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`warden --fix`}
+      lang="bash"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <p>You'll be prompted to accept or reject each fix.</p>
+
+  <h3>Analyze Specific Files</h3>
+
+  <p>Target specific files or directories:</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`warden src/auth.ts
+warden src/api/`}
+      lang="bash"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <h2 id="creating-skills">Creating Skills</h2>
+
+  <p>Skills are markdown files that tell Warden what to look for. They follow the <a href="https://agentskills.io">agentskills.io</a> specification.</p>
+
+  <h3>Directory Structure</h3>
+
+  <p>Create a skill in one of these directories (first match wins):</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`.warden/skills/skill-name/SKILL.md   # Warden-specific (highest priority)
+.agents/skills/skill-name/SKILL.md   # Shared agent skills
+.claude/skills/skill-name/SKILL.md   # Claude Code skills`}
+      lang="text"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <h3>SKILL.md Format</h3>
+
+  <p>A skill has YAML frontmatter for metadata and markdown for the prompt:</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`---
+name: security-review
+description: Review code for security vulnerabilities
+allowed-tools: Read Grep Glob
+---
+
+Review the code for security issues including:
+- SQL injection and parameter binding
+- XSS vulnerabilities in user input handling
+- Hardcoded secrets or credentials
+- Insecure cryptographic practices
+- Path traversal vulnerabilities
+
+Focus on issues in the changed code. For each issue found, report:
+- The specific vulnerability type
+- Why it's a problem
+- How to fix it`}
+      lang="markdown"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <h3>Frontmatter Fields</h3>
+
+  <dl>
+    <dt>name</dt>
+    <dd>Skill identifier (referenced in triggers and CLI)</dd>
+    <dt>description</dt>
+    <dd>Brief description of what the skill does</dd>
+    <dt>allowed-tools</dt>
+    <dd>Space-separated list of tools the skill can use</dd>
+  </dl>
+
+  <h3>Available Tools</h3>
+
+  <p><code>Read</code>, <code>Grep</code>, <code>Glob</code>, <code>Edit</code>, <code>Write</code>, <code>Bash</code>, <code>WebFetch</code>, <code>WebSearch</code></p>
+
+  <p>Most review skills only need <code>Read</code>, <code>Grep</code>, and <code>Glob</code> for exploring context.</p>
+
+  <h3>What Makes a Good Skill</h3>
+
+  <ul>
+    <li><strong>Specific scope</strong>  - One skill, one concern. "Security review" not "code quality"</li>
+    <li><strong>Clear criteria</strong>  - What counts as an issue? What severity?</li>
+    <li><strong>Actionable output</strong>  - Findings should include how to fix</li>
+    <li><strong>Examples</strong>  - Show what good and bad code looks like</li>
+  </ul>
+
+  <h2 id="adding-skills">Adding Skills</h2>
+
+  <p>Warden can discover and install community skills.</p>
+
+  <h3>Interactive Mode</h3>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`warden add`}
+      lang="bash"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <p>Browse available skills and select which to add.</p>
+
+  <h3>List Available Skills</h3>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`warden add --list`}
+      lang="bash"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <h3>Add a Specific Skill</h3>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`warden add security-review`}
+      lang="bash"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <p>This adds the skill and creates a trigger in <code>warden.toml</code>.</p>
+
+  <h2 id="pull-request-reviews">Pull Request Reviews</h2>
+
+  <p>Warden runs automatically on pull requests via GitHub Actions, posting findings as review comments.</p>
+
+  <h3>Organization Setup</h3>
+
+  <p>Add your Anthropic API key as an organization secret so all repos can use it:</p>
+
+  <ol>
+    <li>Go to <strong>Organization Settings → Secrets and variables → Actions</strong></li>
+    <li>Add <code>WARDEN_ANTHROPIC_API_KEY</code> with your key from <a href="https://console.anthropic.com/">console.anthropic.com</a></li>
+  </ol>
+
+  <h3>Repository Setup</h3>
+
+  <p>Initialize Warden in each repository:</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`npx warden init`}
+      lang="bash"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <p>This creates:</p>
+  <ul>
+    <li><code>warden.toml</code>  - Configuration with triggers</li>
+    <li><code>.github/workflows/warden.yml</code>  - GitHub Actions workflow</li>
+  </ul>
+
+  <h3>What Happens on a PR</h3>
+
+  <ol>
+    <li>PR is opened or updated</li>
+    <li>GitHub Actions runs the Warden workflow</li>
+    <li>Warden analyzes changed files against configured triggers</li>
+    <li>Findings are posted as inline review comments</li>
+    <li>Check passes or fails based on <code>failOn</code> severity</li>
+  </ol>
+
+  <h3>Configuring Triggers</h3>
+
+  <p>Triggers map events to skills. Edit <code>warden.toml</code>:</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`version = 1
+
+[[triggers]]
+name = "Security Review"
+event = "pull_request"
+actions = ["opened", "synchronize"]
+skill = "security-review"
+
+[[triggers]]
+name = "API Review"
+event = "pull_request"
+actions = ["opened", "synchronize"]
+skill = "api-review"
+
+[triggers.filters]
+paths = ["src/api/**/*.ts"]`}
+      lang="toml"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <p>See the <a href={`${base}/config`}>Config reference</a> for all trigger options.</p>
+
+  <h3>Controlling Output</h3>
+
+  <p>Configure when to fail and what to comment on:</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`[defaults.output]
+failOn = "high"      # Fail the check on high or critical findings
+commentOn = "medium" # Post comments for medium and above`}
+      lang="toml"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <h2 id="github-app">GitHub App (Optional)</h2>
+
+  <p>By default, Warden posts comments as "github-actions". Create a GitHub App for branded comments that appear from "Warden" with a custom avatar.</p>
+
+  <h3>Create the App</h3>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`npx warden setup-app --org your-org`}
+      lang="bash"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <p>This opens a browser to create and install the app.</p>
+
+  <h3>Add Secrets</h3>
+
+  <p>Add these to your organization secrets:</p>
+
+  <dl>
+    <dt>WARDEN_APP_ID</dt>
+    <dd>App ID from the setup command output</dd>
+    <dt>WARDEN_PRIVATE_KEY</dt>
+    <dd>Private key (full PEM contents)</dd>
+  </dl>
+
+  <h3>Update Workflow</h3>
+
+  <p>Uncomment the GitHub App section in <code>.github/workflows/warden.yml</code>:</p>
+
+  <Terminal showCopy={true}>
+    <Code
+      code={`- uses: actions/create-github-app-token@v1
+  id: app-token
+  with:
+    app-id: \${{ secrets.WARDEN_APP_ID }}
+    private-key: \${{ secrets.WARDEN_PRIVATE_KEY }}
+
+- uses: getsentry/warden-action@v1
+  with:
+    github-token: \${{ steps.app-token.outputs.token }}`}
+      lang="yaml"
+      theme="vitesse-black"
+    />
+  </Terminal>
+
+  <h2 id="tips">Tips</h2>
+
+  <ul>
+    <li><strong><code>--verbose</code></strong>  - See which triggers matched and what Warden is doing</li>
+    <li><strong><code>--fix</code></strong>  - Apply suggested fixes interactively</li>
+    <li><strong><code>--skill &lt;name&gt;</code></strong>  - Skip trigger matching and run one skill directly</li>
+    <li><strong><code>--fail-on &lt;level&gt;</code></strong>  - Override the failure threshold for CI</li>
+    <li><strong><code>-vv</code></strong>  - Debug output with token counts and latencies</li>
+  </ul>
+
+  <p>See the <a href={`${base}/cli`}>CLI reference</a> for all options.</p>
+</Base>
+
+<style>
+  .toc {
+    margin-bottom: 2rem;
+    padding: 1rem 1.25rem;
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: 6px;
+  }
+
+  .toc summary {
+    font-weight: 600;
+    cursor: pointer;
+    color: var(--text-primary);
+    font-size: 0.9rem;
+  }
+
+  .toc ul {
+    margin: 0.5rem 0 0 0;
+    padding-left: 1.25rem;
+    list-style: none;
+  }
+
+  .toc > details > ul {
+    padding-left: 0;
+  }
+
+  .toc li {
+    margin: 0.25rem 0;
+    line-height: 1.4;
+  }
+
+  .toc a {
+    color: var(--text-secondary);
+    text-decoration: none;
+    font-size: 0.875rem;
+  }
+
+  .toc a:hover {
+    color: var(--text-primary);
+    text-decoration: underline;
+  }
+</style>