$ show mitchellh/vouch
Vouch is a community trust management system that lets open-source projects gatekeep contributions behind an explicit vouching mechanism. It maintains a VOUCHED.td file (a flat text format called Trustdown) listing trusted and denounced users. The system provides a Nushell-based CLI for local management, and eight composite GitHub Actions for full GitHub integration: checking issues/PRs on open/reopen, managing vouches via issue or discussion comments, syncing CODEOWNERS, and installing the CLI. The entire implementation is in Nushell script, making it dependency-light (only requires `nu` and `gh`) while achieving surprising sophistication in API handling, retry logic, and file parsing. Architecturally, Vouch is modular: `vouch/file.nu` handles the custom TD file format with full comment/whitespace preservation; `vouch/lib.nu` provides pure-data operations (add, remove, check, denounce) that operate on parsed tables; `vouch/github.nu` wraps the GitHub REST and GraphQL APIs with exponential-backoff retry, collaborator permission checking, and automated commit/push workflows; and `vouch/template.nu` provides a simple template engine for custom response messages. The GitHub Actions in `action/` are composite actions that invoke these Nushell modules directly. The quality of the codebase is notably high for a Nushell project: it follows a disciplined module structure, has comprehensive tests (both fast unit tests and slow integration tests against the live mitchellh/vouch repository), uses typed flags and structured error handling, and implements patterns like retry with rebase for concurrent edits. The TD file parser (`from td`/`to td`) is a particularly well-crafted component that could be extracted as a standalone Nushell module for any project needing a simple, human-readable trust list format. The comment parsing regex patterns are robust against injection and multiline attacks. Overall, Vouch is a well-engineered, self-dogfooded tool that solves a real open-source moderation problem with minimal external dependencies.
The LLM identified 3 files worth highlighting for reuse:
Implements the Trustdown (`.td`) file format parser and serializer: `from td` converts a text file with comments, vouch entries (`username`), denounced entries (`-username`), and optional platform prefixes (`github:user`) into a structured Nushell table; `to td` serializes it back with comments and whitespace preserved. This is a self-contained, reusable module that any Nushell-based project could adopt for managing any flat-file trust list. The design handles edge cases like blank lines, inline reasons, and platform prefixes, and demonstrates careful handling of case-insensitive sorting and roundtrip preservation.
Provides pure data-manipulation operations (`add-user`, `remove-user`, `denounce-user`, `check-user`, `parse-comment`) that operate on parsed TD tables. These functions are platform-agnostic (usable with any source of TD data) and demonstrate a clean functional pipeline: they accept a table by pipe, make transformations, and return a new table. `parse-comment` is a robust regex-based comment parser that supports configurable action keywords and guards against injection via newline truncation. The module is fully testable with no external dependencies beyond the TD parser, making it extractable for any project needing vouching or similar user-status management logic.
Contains the `api` and `graphql` functions that wrap GitHub's REST and GraphQL endpoints with proper authorization (GITHUB_TOKEN env var fallback to `gh auth token`), retry logic with exponential backoff (5 attempts on 401/403/429/5xx), and structured error handling. Also provides `can-manage` for collaborator permission checks including role-name and legacy-permission fallback, and `gh-check-user` for determining vouch status. The retry pattern and API abstraction are reusable in any Nushell script that needs to interact with GitHub APIs, particularly for automation workflows where transient authentication race conditions are common.