From f5320c100015662d3ebec3f8e56529b6b4995272 Mon Sep 17 00:00:00 2001 From: Vito Castellano Date: Mon, 13 Oct 2025 22:19:34 +0200 Subject: [PATCH] docs: update README with v2.0.0 features and improvements Comprehensive README update to reflect new capabilities and improvements --- README.md | 175 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 154 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index a2fcc3f..33bc7dd 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@
Bold Brew Logo

Bold Brew (bbrew)

-

A Homebrew TUI Manager

+

A modern Terminal UI for managing Homebrew packages and casks

@@ -10,6 +10,7 @@ ![GitHub](https://img.shields.io/github/license/Valkyrie00/bold-brew) ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/Valkyrie00/bold-brew/release.yml) ![GolangCI-Lint](https://github.com/Valkyrie00/bold-brew/workflows/Quality/badge.svg) +![Security](https://github.com/Valkyrie00/bold-brew/workflows/Security/badge.svg) ![GitHub all releases](https://img.shields.io/github/downloads/Valkyrie00/bold-brew/total) [![GitHub stars](https://img.shields.io/github/stars/Valkyrie00/bold-brew?style=social)](https://github.com/Valkyrie00/bold-brew/stargazers) @@ -19,13 +20,36 @@
+--- + +
+ +### 🌟 Official Homebrew TUI for Project Bluefin + +Bold Brew is the **official Terminal UI** for managing Homebrew in [**Project Bluefin**](https://projectbluefin.io/), a next-generation Linux desktop that serves tens of thousands of users worldwide. + +*"This application features full package management for homebrew in a nice nerdy interface"* +β€” [Bluefin Documentation](https://docs.projectbluefin.io/command-line/) + +[![Project Bluefin](https://img.shields.io/badge/Featured_in-Project_Bluefin-0091e2?style=for-the-badge&logo=linux)](https://projectbluefin.io/) +[![Universal Blue](https://img.shields.io/badge/Part_of-Universal_Blue-5865f2?style=for-the-badge)](https://universal-blue.org/) + +
+ +--- + ## ✨ Features -- πŸš€ Modern and responsive TUI interface -- πŸ“¦ Simplified Homebrew package management -- πŸ” Advanced package search -- πŸ”„ Real\-time updates -- ⌨️ Intuitive keyboard shortcuts +- πŸš€ **Modern TUI Interface** - Clean and responsive terminal user interface +- πŸ“¦ **Complete Package Management** - Manage both Homebrew formulae and casks +- πŸ” **Advanced Search** - Fast fuzzy search across all packages +- 🎯 **Smart Filters** - Filter by installed, outdated, leaves, or casks +- πŸ“Š **Analytics Integration** - See popular packages based on 90-day download stats +- πŸ”„ **Real-time Updates** - Live feedback during package operations +- ⌨️ **Keyboard Shortcuts** - Intuitive keybindings for all operations +- 🎨 **Type Indicators** - Visual distinction between formulae [F] and casks [C] +- πŸ—‚οΈ **XDG Compliance** - Follows XDG Base Directory Specification for cache storage +- πŸ”’ **Security Scanning** - Automated vulnerability and security checks ## πŸ› οΈ Installation @@ -37,38 +61,130 @@ brew install Valkyrie00/homebrew-bbrew/bbrew ### Manually Download the latest version from the [releases page](https://github.com/Valkyrie00/bold-brew/releases) -## πŸ“– Quick start +## πŸ“– Quick Start Launch the application: ```sh bbrew ``` -### Main Commands -- `/` - Search packages -- `f` - Filter installed packages -- `i` - Install package -- `u` - Update package -- `r` - Remove package -- `q` - Quit -- `Ctrl+U` - Update all packages +### Keyboard Shortcuts + +#### Navigation & Search +- `/` - Search packages (fuzzy search) +- `↑/↓` or `j/k` - Navigate package list +- `Enter` - View package details +- `Esc` - Clear search / Close modals + +#### Filters +- `F` - Filter installed packages +- `O` - Filter outdated packages +- `L` - Filter leaves (explicitly installed, no dependencies) +- `C` - Filter casks only + +#### Package Operations +- `I` - Install selected package +- `U` - Update selected package +- `R` - Remove selected package +- `Ctrl+U` - Update all outdated packages + +#### Other +- `Ctrl+R` - Refresh package database +- `Q` - Quit application +- `?` - Show help (if available) + +## πŸ“‹ What's New in v2.0.0 + +### πŸŽ‰ Major Features +- **Homebrew Casks Support** - Full support for managing GUI applications and binaries +- **Leaves Filter** - Show only explicitly installed packages (excluding dependencies) +- **XDG Base Directory Support** - Cache follows platform standards (`~/.cache/bbrew` on Linux, `~/Library/Caches/bbrew` on macOS) +- **Type Indicators** - Clear visual distinction between formulae `[F]` and casks `[C]` + +### πŸ”§ Technical Improvements +- Updated to Go 1.25 +- Migrated to Podman and OCI-compliant Containerfile +- Enhanced Makefile with 15+ new targets and help system +- Integrated automated security scanning (govulncheck + gosec) +- Fixed implicit memory aliasing issues +- Improved error handling and logging + +### πŸ› Bug Fixes +- Fixed cask analytics endpoint +- Corrected installed casks detection +- Fixed tview special character rendering for type tags +- Improved directory permission handling (0750) ## πŸ–ΌοΈ Screenshots
Main Screenshot +

Main interface with package list and filters

+ Install Screenshot +

Filtered view showing installed packages

+ Search Screenshot +

Fuzzy search in action

+## πŸ”§ Development + +### Prerequisites +- Go 1.25+ +- Homebrew (for testing) +- Podman (optional, for containerized builds) + +### Building from Source +```sh +# Clone the repository +git clone https://github.com/Valkyrie00/bold-brew.git +cd bold-brew + +# Build locally +make build-local + +# Run tests +make test + +# Run linter +make quality-local + +# Run security scans +make security +``` + +### Project Structure +``` +bold-brew/ +β”œβ”€β”€ cmd/bbrew/ # Main application entry point +β”œβ”€β”€ internal/ +β”‚ β”œβ”€β”€ models/ # Data models (Formula, Cask, Package) +β”‚ β”œβ”€β”€ services/ # Business logic (Brew, App, I/O) +β”‚ └── ui/ # TUI components and layout +β”œβ”€β”€ .github/workflows/ # CI/CD pipelines +└── Makefile # Build automation +``` + ## 🀝 Contributing Contributions are welcome! Please: 1. 🍴 Fork the project -2. πŸ”¨ Create your feature branch -3. πŸ“ Commit your changes -4. πŸš€ Submit a pull request +2. πŸ”¨ Create your feature branch (`git checkout -b feat/amazing-feature`) +3. πŸ“ Commit your changes using [Conventional Commits](https://www.conventionalcommits.org/) +4. πŸ§ͺ Run tests and linters (`make test quality-local`) +5. πŸš€ Push to the branch (`git push origin feat/amazing-feature`) +6. πŸ“¬ Open a Pull Request + +### Commit Message Format +We follow Conventional Commits: +- `feat:` - New features +- `fix:` - Bug fixes +- `docs:` - Documentation changes +- `refactor:` - Code refactoring +- `chore:` - Maintenance tasks +- `test:` - Test updates ## 🦸Contributors Bold Brew exists thanks to the efforts of these wonderful people @@ -81,12 +197,29 @@ Bold Brew exists thanks to the efforts of these wonderful people This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +## πŸ›‘οΈ Security + +Security is a priority for Bold Brew. We use: +- **govulncheck** - Go vulnerability database scanning +- **gosec** - Static security analysis +- **Automated CI/CD** - Security checks on every PR and push + +Found a security issue? Please report it privately via [GitHub Security Advisories](https://github.com/Valkyrie00/bold-brew/security/advisories). + +## πŸ“Š Platform Support + +| Platform | Support | Notes | +|----------|---------|-------| +| 🍎 **macOS** | βœ… Full | Native Homebrew support | +| 🐧 **Linux** | βœ… Full | Linuxbrew/Homebrew support | + ## πŸ’– Support -- 🌟 Star the project -- πŸ› [Report a bug](https://github.com/Valkyrie00/bold-brew/issues) -- πŸ’‘ [Propose new features](https://github.com/Valkyrie00/bold-brew/issues) +- 🌟 [Star the project](https://github.com/Valkyrie00/bold-brew) +- πŸ› [Report a bug](https://github.com/Valkyrie00/bold-brew/issues/new?labels=bug) +- πŸ’‘ [Request a feature](https://github.com/Valkyrie00/bold-brew/issues/new?labels=enhancement) - πŸ“£ Share the project with your friends +- β˜• [Sponsor the project](https://github.com/sponsors/Valkyrie00) (if available) ---