gatehouse-crunchtools 0.5.0__tar.gz

gatehouse_crunchtools-0.5.0/.gemini/config.yaml

@@ -0,0 +1,6 @@
+code_review:
+  ignore:
+    - "vendor/**"
+    - "*.min.js"
+    - ".gourmand-cache/**"
+    - "*.lock"

gatehouse_crunchtools-0.5.0/.gemini/styleguide.md

@@ -0,0 +1,27 @@
+# Gatehouse Style Guide
+
+## Architecture
+
+Gatehouse is a Python CLI tool with 5 concurrent Gemini agents for code review.
+
+### Module Structure
+- `cli.py` -- argparse entry point
+- `agents.py` -- agent prompt definitions (frozen dataclasses)
+- `diffview.py` -- unified diff to structured BEFORE/AFTER view for agents
+- `gemini.py` -- httpx async client for Gemini REST API
+- `review.py` -- orchestration (git diff, concurrent agents, exit codes)
+- `output.py` -- formatted terminal output with ANSI colors
+
+### Conventions
+- Python 3.11+, strict mypy, ruff linting
+- httpx for HTTP (no vendor SDKs)
+- argparse (stdlib) for CLI (no click/typer)
+- All API calls mocked in tests (no live calls in CI)
+- Exit 0 = success/advisory, Exit 1 = blocking findings, Exit 2 = usage error
+- Respect NO_COLOR environment variable
+- Structured output to stdout, diagnostics to stderr
+
+### What NOT to Flag
+- The agent prompt strings are intentionally long -- do not suggest splitting them
+- The `dict[str, Any]` types for JSON findings are intentional -- no Pydantic models needed here
+- subprocess calls to git are safe and expected

gatehouse_crunchtools-0.5.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,68 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear description of the bug
+      placeholder: What happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: How can we reproduce this bug?
+      placeholder: |
+        1. Run `gatehouse --base main`
+        2. Observe error '...'
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened? Include error messages if available.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install_method
+    attributes:
+      label: Installation Method
+      description: How are you running gatehouse?
+      options:
+        - uv tool install
+        - pipx install
+        - Container (podman run)
+        - From source (uv sync)
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: Output of `gatehouse --help` header or check pyproject.toml
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other relevant information (logs, git state, environment)

gatehouse_crunchtools-0.5.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Gemini API Documentation
+    url: https://ai.google.dev/gemini-api/docs
+    about: Check the Google Gemini API docs for API behavior questions

gatehouse_crunchtools-0.5.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,49 @@
+name: Feature Request
+description: Suggest a new feature or enhancement
+title: "[Feature]: "
+labels: ["enhancement", "triage"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: What problem does this feature solve?
+      placeholder: I need to...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: Describe the feature or change you'd like
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: What alternatives have you considered?
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Area
+      description: Which area does this feature belong to?
+      options:
+        - Agent prompts (bug-hunter, security-scan, etc.)
+        - Output formatting
+        - CLI flags / interface
+        - API client (Gemini integration)
+        - New agent
+        - CI / integration
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other relevant information or examples

gatehouse_crunchtools-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run linter
+        run: uv run ruff check src tests
+
+      - name: Run type checker
+        run: uv run mypy src
+
+      - name: Run tests
+        run: uv run pytest -v
+
+  # Gatehouse code review runs in its own workflow (gatehouse.yml) on
+  # pull_request_target, so it covers fork PRs too. See that file.
+
+  # Call our own reusable workflow rather than inlining the job. Gatehouse
+  # hosts gourmand.yml for the whole fleet; keeping a private copy here is the
+  # copy-paste drift RT #1468 was filed about.
+  gourmand-review:
+    uses: ./.github/workflows/gourmand.yml
+
+  build-container:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build container image
+        run: docker build -f Containerfile -t gatehouse:test .
+
+  validate-constitution:
+    name: Constitution Validation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/checkout@v4
+        with:
+          repository: crunchtools/constitution
+          path: .constitution
+
+      - name: Validate constitution
+        run: python3 .constitution/validate-constitution.py .specify/memory/constitution.md --verbose

gatehouse_crunchtools-0.5.0/.github/workflows/container.yml

@@ -0,0 +1,112 @@
+name: Container Build & Push
+
+on:
+  push:
+    branches: [master]
+    tags: ["v*"]
+  pull_request:
+    branches: [master]
+  workflow_dispatch:
+
+env:
+  QUAY_IMAGE: quay.io/crunchtools/gatehouse
+  GHCR_IMAGE: ghcr.io/crunchtools/gatehouse
+
+jobs:
+  build-and-push-quay:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Quay.io
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: quay.io
+          username: ${{ secrets.QUAY_USERNAME }}
+          password: ${{ secrets.QUAY_PASSWORD }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.QUAY_IMAGE }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Containerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Run Trivy vulnerability scanner
+        continue-on-error: true
+        if: github.event_name != 'pull_request'
+        uses: aquasecurity/trivy-action@master
+        with:
+          image-ref: ${{ env.QUAY_IMAGE }}:latest
+          format: "table"
+          exit-code: "0"
+          severity: "CRITICAL,HIGH"
+
+  build-and-push-ghcr:
+    runs-on: ubuntu-latest
+    needs: build-and-push-quay
+    if: github.event_name != 'pull_request'
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ github.token }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.GHCR_IMAGE }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Containerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

gatehouse_crunchtools-0.5.0/.github/workflows/gatehouse.yml

@@ -0,0 +1,54 @@
+# Gatehouse dogfoods its own fork-safe review on EVERY PR — internal or external.
+#
+# This is the exact pattern shipped to adopters in examples/gatehouse.yml, except
+# it references the reusable workflow locally (./.github/workflows/review.yml)
+# instead of by tag. pull_request_target runs the trusted base-branch version of
+# these files, so a PR can neither disable the guard nor tamper with the reviewer.
+
+name: Gatehouse
+
+on:
+  pull_request_target:
+    branches: [master]
+    types: [opened, synchronize, reopened]
+
+permissions: {}   # default-deny; each job grants only what it needs
+
+jobs:
+  # 1) Reject PRs from outside contributors that modify workflow files.
+  guard:
+    name: Protect workflows
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Reject workflow changes from untrusted PRs
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR: ${{ github.event.pull_request.number }}
+          AUTHOR_ASSOC: ${{ github.event.pull_request.author_association }}
+        run: |
+          set -euo pipefail
+          case "$AUTHOR_ASSOC" in
+            OWNER|MEMBER|COLLABORATOR)
+              echo "Author '$AUTHOR_ASSOC' is trusted; allowing."; exit 0 ;;
+          esac
+          changed="$(gh pr diff "$PR" --repo "$GITHUB_REPOSITORY" --name-only)"
+          if echo "$changed" | grep -qE '^\.github/workflows/'; then
+            echo "::error::PR modifies .github/workflows/ — not accepted from external contributors."
+            gh pr comment "$PR" --repo "$GITHUB_REPOSITORY" --body \
+              $'🚫 **Workflow changes are not accepted via pull request.** Please open an issue and a maintainer will make the change.'
+            exit 1
+          fi
+          echo "No workflow files changed."
+
+  # 2) Review the PR diff (no checkout, BYO key) via the reusable workflow.
+  review:
+    name: Gatehouse review
+    permissions:
+      contents: read
+      pull-requests: write
+    uses: ./.github/workflows/review.yml
+    secrets:
+      GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

gatehouse_crunchtools-0.5.0/.github/workflows/gourmand.yml

@@ -0,0 +1,46 @@
+# Gourmand — AI slop detection (reusable workflow)
+#
+# Runs the pinned Gourmand container against the caller repo. Centralizing
+# the job body here means a fix or image change reaches every adopter on
+# their next CI run instead of sitting frozen in a copy-pasted snapshot.
+#
+# Filed per RT #1468: a dead `cargo install --git codeberg.org/mattdm/gourmand`
+# gate kept regenerating fleet-wide because the old `examples/gourmand.yml`
+# was a copy-paste snippet, not a `workflow_call` reference — fixing it in one
+# repo never propagated to the repos that had already copied it. Do not go
+# back to a copy-paste example; that is the exact bug this workflow fixes.
+#
+# ── How adopters use it ──────────────────────────────────────────────────────
+# Add this job to your CI workflow:
+#
+#   jobs:
+#     gourmand:
+#       name: Code Quality (Gourmand)
+#       uses: crunchtools/gatehouse/.github/workflows/gourmand.yml@v0.5.0
+
+name: Gourmand (reusable)
+
+on:
+  workflow_call:
+    inputs:
+      path:
+        description: "Path to scan (default: repo root)"
+        type: string
+        required: false
+        default: "."
+      image:
+        description: "Gourmand image ref. Override to pin a specific digest/tag."
+        type: string
+        required: false
+        default: "quay.io/crunchtools/gourmand:latest"
+
+jobs:
+  gourmand:
+    name: Code Quality (Gourmand)
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ inputs.image }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run Gourmand
+        run: gourmand --full ${{ inputs.path }}

gatehouse_crunchtools-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

gatehouse_crunchtools-0.5.0/.github/workflows/review.yml

@@ -0,0 +1,134 @@
+# Gatehouse — fork-safe PR review (reusable workflow)
+#
+# Hardened `pull_request_target` review: diff-piped, NO checkout, scoped-secret-bound.
+# Reviews fork PRs with a bring-your-own Gemini key and zero hosting. Safe by
+# construction: the fork's code is only ever read as a unified DIFF on stdin —
+# never checked out to disk, never executed. The container runs `gatehouse`,
+# which is diff-in -> Gemini -> PR-review-comments-out.
+#
+# ── How adopters use it ──────────────────────────────────────────────────────
+# Add `.github/workflows/gatehouse.yml` to your repository:
+#
+#   name: Gatehouse Review
+#   on:
+#     pull_request_target:
+#       types: [opened, synchronize, reopened]
+#   permissions: {}                 # default-deny at the top level
+#   jobs:
+#     review:
+#       permissions:                # grant ONLY what the review needs
+#         contents: read
+#         pull-requests: write
+#       uses: crunchtools/gatehouse/.github/workflows/review.yml@v1
+#       secrets:
+#         GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+#
+# ── Scoped secret (recommended) ──────────────────────────────────────────────
+# Configure GEMINI_API_KEY as a *scoped* secret bound to this trusted reusable
+# workflow (Settings -> Secrets and variables -> Actions -> scope to
+# `crunchtools/gatehouse/.github/workflows/review.yml`). Then no other job in the
+# caller's repo can read the key — closing the "extra job under pull_request_target"
+# footgun. (GitHub 2026 Actions roadmap; verify availability for your plan.)
+#
+# ── Why this is safe under pull_request_target ───────────────────────────────
+#   1. No `actions/checkout` of the fork head — nothing on disk to execute.
+#      (Also sidesteps the actions/checkout v7 fork-head block entirely.)
+#   2. The diff arrives as data on stdin; `gatehouse --stdin` never runs `git`
+#      against, builds, installs, or executes the PR.
+#   3. The image is pinned to a release tag; the run step invokes only the container
+#      entrypoint — no repo-defined tooling runs.
+#   4. Least-privilege GITHUB_TOKEN: contents:read + pull-requests:write.
+# -----------------------------------------------------------------------------
+
+name: Gatehouse Review (reusable)
+
+on:
+  workflow_call:
+    inputs:
+      model:
+        description: "Gemini model override (default: gatehouse built-in)"
+        type: string
+        required: false
+        default: ""
+      agents:
+        description: "Comma-separated agent slugs (default: all agents)"
+        type: string
+        required: false
+        default: ""
+      blocking:
+        # Advisory by default: the review posts findings as PR comments but the
+        # check ALWAYS passes (exit 0), so a non-deterministic LLM finding can
+        # never block a merge. Opt in with `blocking: true` only if you want
+        # critical/high findings from blocking agents to fail the check. Even
+        # then, do NOT mark this a *required* status check — see examples/.
+        description: "Fail the check on blocking findings (default: advisory)."
+        type: boolean
+        required: false
+        default: false
+      image:
+        # Pinned to the immutable release TAG, not a digest: our registry prunes
+        # untagged manifests on rebuild, so a digest pin dies the next time the
+        # tag is rebuilt. The release tag is controlled and not rebuilt casually.
+        description: "Gatehouse release image tag. Bump per release."
+        type: string
+        required: false
+        default: "quay.io/crunchtools/gatehouse:0.4.0"
+    secrets:
+      GEMINI_API_KEY:
+        required: true
+
+jobs:
+  review:
+    name: Gatehouse Code Review
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read          # read PR metadata / diff via the API
+      pull-requests: write    # post the review (REQUEST_CHANGES / COMMENT)
+    steps:
+      - name: Review fork diff (no checkout, never executes PR code)
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          # Trusted base repo + base-branch SHA — styleguide/constitution are
+          # loaded from HERE via the API, never from the fork head.
+          BASE_REF: ${{ github.event.pull_request.base.sha }}
+          IMAGE: ${{ inputs.image }}
+          MODEL: ${{ inputs.model }}
+          AGENTS: ${{ inputs.agents }}
+          BLOCKING: ${{ inputs.blocking }}
+        run: |
+          set -euo pipefail
+
+          # This reusable workflow only makes sense under pull_request_target,
+          # where a fork PR's GITHUB_TOKEN/secrets are available in the BASE
+          # repo's trusted context. Fail loudly if there is no PR context.
+          if [ -z "${PR_NUMBER:-}" ]; then
+            echo "::error::No pull_request context. Call this from 'on: pull_request_target'." >&2
+            exit 1
+          fi
+
+          # Optional passthrough flags (only added when provided).
+          # Advisory by default: unless the caller sets `blocking: true`, add
+          # --advisory so gatehouse exits 0 regardless of findings. The review
+          # is still posted; it just never fails the check.
+          args=( --stdin --comment )
+          [ "$BLOCKING" = "true" ] || args+=( --advisory )
+          [ -n "$MODEL" ]  && args+=( --model "$MODEL" )
+          [ -n "$AGENTS" ] && args+=( --agents "$AGENTS" )
+
+          # 1) Fetch the PR diff over the API — data only, no fork code on disk.
+          # 2) Pipe it into the release-tag-pinned container's `gatehouse --stdin --comment`.
+          #    - GITHUB_REF is synthesized as refs/pull/N/merge so gatehouse's
+          #      detect_pr_context() resolves (repo, PR) without mounting the event file.
+          #    - GITHUB_TOKEN authorizes gatehouse to POST the PR review via the REST API.
+          gh pr diff "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --patch \
+            | docker run --rm -i \
+                -e GEMINI_API_KEY \
+                -e GITHUB_TOKEN="$GH_TOKEN" \
+                -e GITHUB_REPOSITORY="$GITHUB_REPOSITORY" \
+                -e GITHUB_REF="refs/pull/${PR_NUMBER}/merge" \
+                -e GATEHOUSE_CONTEXT_REPO="$GITHUB_REPOSITORY" \
+                -e GATEHOUSE_CONTEXT_REF="$BASE_REF" \
+                "$IMAGE" \
+                "${args[@]}"