@brett.buskirk/agent-gate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brett Buskirk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,196 @@
+# AgentGate
+
+**Guardrail checks for AI-agent-generated pull requests.**
+
+AgentGate runs in CI on every PR, inspects the diff for the risk signals that AI agents commonly introduce — leaked secrets, out-of-scope changes, missing tests, surprise dependencies — posts a structured review comment, and sets a pass/fail check. Your team gets eyes on agent work without rubber-stamping it.
+
+> Built by [Brett Buskirk LLC](https://brett-buskirk.dev) as part of the **Agentic Development Workflow Setup** service — a productized safety net for teams shipping with AI coding agents.
+
+---
+
+## Status
+
+**v0.1.0 — active development.** All six rules implemented and tested. Action bundled (`dist/index.js`). Dogfood CI runs AgentGate on its own PRs. npm publish next.
+
+---
+
+## Quickstart
+
+### GitHub Action
+
+```yaml
+# .github/workflows/agentgate.yml
+name: AgentGate
+on: [pull_request]
+
+jobs:
+  agentgate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: brett-buskirk/agent-gate@v1
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Add a `.agentgate.yml` to your repo to configure it (or skip it — the defaults are sane).
+
+### CLI
+
+```bash
+npx @brett.buskirk/agent-gate check --base main
+```
+
+Or install globally:
+
+```bash
+npm install -g @brett.buskirk/agent-gate
+agent-gate check --base main --json
+```
+
+---
+
+## Configuration
+
+Place a `.agentgate.yml` in your repo root. Everything has a default — the file is optional.
+
+```yaml
+version: 1
+fail_on: error          # error | warning | never
+comment: true           # post/update a PR comment
+
+rules:
+  secrets:
+    enabled: true
+    severity: error
+
+  scope:
+    enabled: true
+    severity: error
+    allow:               # if set, only these paths are permitted
+      - "src/**"
+      - "test/**"
+      - "docs/**"
+    deny:                # always blocked regardless of allow
+      - ".github/workflows/**"
+      - "infra/**"
+      - "**/*.lock"
+      - "package-lock.json"
+
+  diff_size:
+    enabled: true
+    severity: warning
+    max_files: 30
+    max_lines: 800
+
+  tests_required:
+    enabled: true
+    severity: warning
+    src_globs: ["src/**"]
+    test_globs: ["**/*.test.*", "**/*.spec.*", "tests/**"]
+
+  dependencies:
+    enabled: true
+    severity: warning
+    manifests: ["package.json", "requirements.txt", "go.mod", "Gemfile", "Cargo.toml"]
+
+  dangerous_patterns:
+    enabled: true
+    severity: error
+    patterns:
+      - "eval\\("
+      - "--no-verify"
+      - "child_process\\.exec\\("
+```
+
+### `fail_on`
+
+| Value | Behavior |
+|-------|----------|
+| `error` | Only error-severity findings fail the check (default) |
+| `warning` | Warnings also fail the check |
+| `never` | Check always passes; findings are still reported |
+
+---
+
+## Rules
+
+| Rule | Default severity | What it catches |
+|------|-----------------|-----------------|
+| `secrets` | error | AWS keys, GitHub tokens, private key blocks, high-entropy assignments |
+| `scope` | error | Files outside the allow list or inside the deny list |
+| `diff_size` | warning | PRs exceeding `max_files` (30) or `max_lines` (800) |
+| `tests_required` | warning | Source changes with no corresponding test file changes |
+| `dependencies` | warning | Modified dependency manifests (supply-chain risk) |
+| `dangerous_patterns` | error | User-defined regex denylist applied to added lines |
+
+---
+
+## PR Comment
+
+AgentGate posts a single comment on the PR and updates it in place on re-runs — never spams. The comment shows the overall verdict, a rule-by-rule summary table, and expandable findings with file locations and actionable suggestions.
+
+---
+
+## How it works
+
+1. On a `pull_request` event, the Action fetches the PR diff from the GitHub API
+2. The diff is parsed into a structured model (files, chunks, added/removed lines)
+3. Each enabled rule runs over the model and returns findings
+4. The engine aggregates findings and computes a verdict based on `fail_on`
+5. Reporters post the PR comment, set the check status, and write the Step Summary
+6. The check fails if the verdict is `fail` — blocking merge until the agent's work is reviewed
+
+The CLI (`agent-gate check`) uses `git diff` instead of the GitHub API, making it usable locally and in pre-commit hooks.
+
+---
+
+## Project structure
+
+```
+agent-gate/
+  action.yml              # GitHub Action metadata
+  src/
+    cli.ts                # CLI entry (commander)
+    action.ts             # Action entry
+    engine.ts             # Aggregates rules → verdict
+    diff/                 # Diff providers + parser
+    rules/                # Rule implementations
+    report/               # Reporters (comment, check, summary, CLI)
+    config/               # Schema (zod) + loader
+    utils/                # Glob matching
+  test/
+    fixtures/             # Sample diffs (clean + dirty per rule)
+    rules/                # Rule unit tests
+    engine.test.ts
+  docs/
+    DESIGN.md
+    SPRINTS.md
+```
+
+---
+
+## Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Language | TypeScript 5, strict mode |
+| Runtime | Node 20+ |
+| Action bundler | @vercel/ncc |
+| Config validation | zod |
+| Config format | js-yaml |
+| CLI | commander |
+| GitHub API | @actions/github (Octokit) |
+| Tests | Vitest |
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). New rules are the most welcome contribution — there's a dedicated issue template and a clear pattern to follow.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/action.yml

@@ -0,0 +1,30 @@
+name: 'AgentGate'
+description: 'Guardrail checks for AI-agent-generated pull requests'
+author: 'Brett Buskirk'
+
+inputs:
+  github-token:
+    description: 'GitHub token for API access'
+    required: true
+    default: ${{ github.token }}
+  config-path:
+    description: 'Path to .agentgate.yml config file'
+    required: false
+    default: '.agentgate.yml'
+  fail-on:
+    description: 'Minimum severity that fails the check (error | warning | never). Overrides config file.'
+    required: false
+
+outputs:
+  verdict:
+    description: 'Overall verdict: pass | warn | fail'
+  finding-count:
+    description: 'Total number of findings'
+
+runs:
+  using: 'node20'
+  main: 'dist/index.js'
+
+branding:
+  icon: 'shield'
+  color: 'blue'

package/bin/agent-gate.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+'use strict'
+require('../lib/cli.js')

package/lib/action.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=action.d.ts.map

package/lib/action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":""}

package/lib/action.js

@@ -0,0 +1,73 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const core = __importStar(require("@actions/core"));
+const github = __importStar(require("@actions/github"));
+const load_1 = require("./config/load");
+const github_1 = require("./diff/github");
+const engine_1 = require("./engine");
+const comment_1 = require("./report/comment");
+const checkRun_1 = require("./report/checkRun");
+const summary_1 = require("./report/summary");
+async function run() {
+    try {
+        const token = core.getInput('github-token', { required: true });
+        const configPath = core.getInput('config-path') || '.agentgate.yml';
+        const { pull_request } = github.context.payload;
+        if (!pull_request) {
+            core.warning('AgentGate only runs on pull_request events. Skipping.');
+            return;
+        }
+        core.info(`Running AgentGate on PR #${pull_request.number}`);
+        const config = (0, load_1.loadConfig)(configPath);
+        const failOnOverride = core.getInput('fail-on');
+        if (failOnOverride && ['error', 'warning', 'never'].includes(failOnOverride)) {
+            config.fail_on = failOnOverride;
+        }
+        const { owner, repo } = github.context.repo;
+        const provider = new github_1.GitHubDiffProvider(token, owner, repo, pull_request.number);
+        const diff = await provider.getDiff();
+        const result = (0, engine_1.runEngine)(diff, config);
+        (0, checkRun_1.setCheckOutput)(result);
+        if (config.comment) {
+            await (0, comment_1.upsertComment)(token, owner, repo, pull_request.number, result, diff);
+        }
+        await (0, summary_1.writeSummary)(result, diff);
+    }
+    catch (err) {
+        core.setFailed(err instanceof Error ? err.message : String(err));
+    }
+}
+run();

package/lib/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/lib/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/lib/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const load_1 = require("./config/load");
+const git_1 = require("./diff/git");
+const engine_1 = require("./engine");
+const json_1 = require("./report/json");
+const program = new commander_1.Command();
+program
+    .name('agent-gate')
+    .description('Guardrail checks for AI-agent-generated pull requests')
+    .version('0.1.0');
+program
+    .command('check')
+    .description('Run guardrail checks against a diff')
+    .option('-b, --base <ref>', 'Base git ref to diff against', 'main')
+    .option('-c, --config <path>', 'Path to config file', '.agentgate.yml')
+    .option('--json', 'Output results as JSON')
+    .action(async (opts) => {
+    try {
+        const config = (0, load_1.loadConfig)(opts.config);
+        const provider = new git_1.GitDiffProvider(opts.base);
+        const diff = await provider.getDiff();
+        const result = (0, engine_1.runEngine)(diff, config);
+        (0, json_1.reportCli)(result, diff, opts.json);
+        if (result.verdict === 'fail') {
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error('Error:', err instanceof Error ? err.message : String(err));
+        process.exit(2);
+    }
+});
+program.parse();

package/lib/config/load.d.ts

@@ -0,0 +1,3 @@
+import type { Config } from './schema';
+export declare function loadConfig(configPath: string): Config;
+//# sourceMappingURL=load.d.ts.map

package/lib/config/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/config/load.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAQrD"}

package/lib/config/load.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+const fs_1 = require("fs");
+const js_yaml_1 = require("js-yaml");
+const schema_1 = require("./schema");
+function loadConfig(configPath) {
+    if (!(0, fs_1.existsSync)(configPath)) {
+        return schema_1.ConfigSchema.parse({ version: 1 });
+    }
+    const raw = (0, fs_1.readFileSync)(configPath, 'utf8');
+    const parsed = (0, js_yaml_1.load)(raw);
+    return schema_1.ConfigSchema.parse(parsed);
+}

package/lib/config/schema.d.ts

@@ -0,0 +1,236 @@
+import { z } from 'zod';
+export declare const ConfigSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    fail_on: z.ZodDefault<z.ZodEnum<["error", "warning", "never"]>>;
+    comment: z.ZodDefault<z.ZodBoolean>;
+    rules: z.ZodDefault<z.ZodObject<{
+        secrets: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            severity: z.ZodDefault<z.ZodEnum<["error", "warning", "info"]>>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+        }, {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+        }>>;
+        scope: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            severity: z.ZodDefault<z.ZodEnum<["error", "warning", "info"]>>;
+            allow: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            deny: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+            deny: string[];
+            allow?: string[] | undefined;
+        }, {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+            allow?: string[] | undefined;
+            deny?: string[] | undefined;
+        }>>;
+        diff_size: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            severity: z.ZodDefault<z.ZodEnum<["error", "warning", "info"]>>;
+            max_files: z.ZodDefault<z.ZodNumber>;
+            max_lines: z.ZodDefault<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+            max_files: number;
+            max_lines: number;
+        }, {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+            max_files?: number | undefined;
+            max_lines?: number | undefined;
+        }>>;
+        tests_required: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            severity: z.ZodDefault<z.ZodEnum<["error", "warning", "info"]>>;
+            src_globs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            test_globs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+            src_globs: string[];
+            test_globs: string[];
+        }, {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+            src_globs?: string[] | undefined;
+            test_globs?: string[] | undefined;
+        }>>;
+        dependencies: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            severity: z.ZodDefault<z.ZodEnum<["error", "warning", "info"]>>;
+            manifests: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+            manifests: string[];
+        }, {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+            manifests?: string[] | undefined;
+        }>>;
+        dangerous_patterns: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            severity: z.ZodDefault<z.ZodEnum<["error", "warning", "info"]>>;
+            patterns: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+            patterns: string[];
+        }, {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+            patterns?: string[] | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        secrets: {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+        };
+        scope: {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+            deny: string[];
+            allow?: string[] | undefined;
+        };
+        diff_size: {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+            max_files: number;
+            max_lines: number;
+        };
+        tests_required: {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+            src_globs: string[];
+            test_globs: string[];
+        };
+        dependencies: {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+            manifests: string[];
+        };
+        dangerous_patterns: {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+            patterns: string[];
+        };
+    }, {
+        secrets?: {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+        } | undefined;
+        scope?: {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+            allow?: string[] | undefined;
+            deny?: string[] | undefined;
+        } | undefined;
+        diff_size?: {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+            max_files?: number | undefined;
+            max_lines?: number | undefined;
+        } | undefined;
+        tests_required?: {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+            src_globs?: string[] | undefined;
+            test_globs?: string[] | undefined;
+        } | undefined;
+        dependencies?: {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+            manifests?: string[] | undefined;
+        } | undefined;
+        dangerous_patterns?: {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+            patterns?: string[] | undefined;
+        } | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    fail_on: "error" | "warning" | "never";
+    comment: boolean;
+    rules: {
+        secrets: {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+        };
+        scope: {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+            deny: string[];
+            allow?: string[] | undefined;
+        };
+        diff_size: {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+            max_files: number;
+            max_lines: number;
+        };
+        tests_required: {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+            src_globs: string[];
+            test_globs: string[];
+        };
+        dependencies: {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+            manifests: string[];
+        };
+        dangerous_patterns: {
+            enabled: boolean;
+            severity: "error" | "warning" | "info";
+            patterns: string[];
+        };
+    };
+}, {
+    version: 1;
+    fail_on?: "error" | "warning" | "never" | undefined;
+    comment?: boolean | undefined;
+    rules?: {
+        secrets?: {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+        } | undefined;
+        scope?: {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+            allow?: string[] | undefined;
+            deny?: string[] | undefined;
+        } | undefined;
+        diff_size?: {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+            max_files?: number | undefined;
+            max_lines?: number | undefined;
+        } | undefined;
+        tests_required?: {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+            src_globs?: string[] | undefined;
+            test_globs?: string[] | undefined;
+        } | undefined;
+        dependencies?: {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+            manifests?: string[] | undefined;
+        } | undefined;
+        dangerous_patterns?: {
+            enabled?: boolean | undefined;
+            severity?: "error" | "warning" | "info" | undefined;
+            patterns?: string[] | undefined;
+        } | undefined;
+    } | undefined;
+}>;
+export type Config = z.infer<typeof ConfigSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/lib/config/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4DvB,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC"}