@sentry/warden 0.1.1 → 0.3.0

package/docs/src/pages/guide.astro

@@ -1,450 +0,0 @@
----
-import Base from '../layouts/Base.astro';
-import Terminal from '../components/Terminal.astro';
-import { Code } from 'astro:components';
-import { WARDEN_ACTION } from '../utils/version.js';
-
-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: ${WARDEN_ACTION}
-  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>