CaskFlow

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 9 Open GitHub ↗

Classification tool & Pipeline for HomeBrew Casks

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# CaskFlow

[![Tests](https://github.com/alielsokary/CaskFlow/actions/workflows/tests.yml/badge.svg)](https://github.com/alielsokary/CaskFlow/actions/workflows/tests.yml)
[![Codacy](https://app.codacy.com/project/badge/Grade/825c27dd6a6141afb36aa99fe880239f)](https://app.codacy.com/gh/alielsokary/CaskFlow/dashboard)
[![codecov](https://codecov.io/gh/alielsokary/CaskFlow/branch/develop/graph/badge.svg)](https://codecov.io/gh/alielsokary/CaskFlow)
[![Latest release](https://img.shields.io/github/v/release/alielsokary/CaskFlow)](https://github.com/alielsokary/CaskFlow/releases/latest)
[![License](https://img.shields.io/github/license/alielsokary/CaskFlow)](https://raw.githubusercontent.com/alielsokary/CaskFlow/master/LICENSE)

CaskFlow turns the live Homebrew cask catalog into reviewed, release-ready metadata for [CaskHub](https://github.com/alielsokary/CaskHub). It classifies applications, tracks when casks were added, extracts vendor icons safely, and publishes versioned assets that CaskHub can consume with a bundled fallback.

## What CaskFlow publishes

| Asset | Purpose | Source |
|---|---|---|
| `categories.json` | Canonical cask-to-category mapping, taxonomy, release tag, and optional icon manifest | Repository and [latest release](https://github.com/alielsokary/CaskFlow/releases/latest) |
| `added_dates.json` | Earliest known Homebrew addition date for each cask | Generated for each release |
| `<token>.png` | 256×256 application icons | Orphan [`icons` branch](https://github.com/alielsokary/CaskFlow/tree/icons) |

The taxonomy has 17 primary categories and one secondary-only `ai` trait. Each cask has exactly one primary category and up to two distinct secondary categories. See the [classification guide](docs/CLASSIFICATION_GUIDE.md) for category boundaries and review rules.

## How it works

```mermaid
flowchart LR
    brew["Homebrew cask API"] --> diff["Diff and homepage metadata"]
    diff --> classify["Validated classification"]
    classify --> review["Semantic, assigned PR"]
    review --> release["Versioned release assets"]
    brew --> dates["Mine added dates daily"]
    dates --> release
    brew --> icons["Safe icon extraction"]
    icons --> branch["icons branch"]
    release --> caskhub["CaskHub"]
    branch --> caskhub
```

The daily classification workflow adds new casks, migrates Homebrew token renames, and prunes removed or disabled entries. Provider and validation failures are skipped for a later retry. Results below `0.75` confidence remain in an assigned PR for manual review; higher-confidence updates may auto-merge after required checks pass.

The release workflow runs daily independently of classification, stamps `categories.json` with its release tag and current icon-token manifest when available, and mines `added_dates.json` directly from Homebrew's history. Before publishing, it verifies that every cask in the tap's current tree has an added date. A category merge also triggers it immediately. Classification updates therefore do not delay Recently Added data, and date refreshes do not require an LLM result or category assignment.

Icons are downloaded from vendor artifacts, checksum-verified, expanded without running installer scripts, and converted from the application bundle's `.icns` file. The full safety and audit protocol is in [Icon Extraction](docs/ICON_EXTRACTION.md).

## Local development

Python 3.12 or newer is recommended.

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Deterministic preview; repository files remain unchanged.
LLM_PROVIDER=mock python scripts/classify_new_casks.py --dry-run

# Test suite and coverage report.
pytest --cov=scripts --cov-report=term-missing
```

Real classification supports `anthropic`, `openai`, `groq`, and `cloudflare`; choose one with `LLM_PROVIDER` and provide that service's credentials. `mock` is intended for deterministic local verification.

## Repository guide

- [`scripts/`](scripts) contains the maintained classification, correction, release-data, and icon tooling.
- [`tests/`](tests) covers schema rules and the highest-risk pipeline behavior.
- [`data/`](data) holds generated reports, caches, and reviewed correction input; it is not the canonical category source.
- [`.github/workflows/`](.github/workflows) contains classification, icon, release, and verification automation.

## Projects using CaskFlow

| Project | Description | Categories | Added&nbsp;Dates | Icons |
|---|---|:---:|:---:|:---:|
| [CaskHub](https://github.com/alielsokary/CaskHub) | Native macOS app for discovering, installing, and managing Homebrew casks | ✅ | ✅ | ✅ |
| [Applite](https://github.com/milanvarady/Applite) | User-friendly GUI macOS application for Homebrew casks | - | - | ✅ |
| [*Add&nbsp;yours*](https://github.com/alielsokary/CaskFlow/edit/develop/README.md) | Using CaskFlow data in your project? Add it to this table | - | - | - |

## Attribution

CaskFlow is [MIT licensed](LICENSE), so no attribution is required beyond the license terms. If your project consumes CaskFlow data (categories, added dates, or icons), a visible credit with a link back is very much appreciated, for example:

> Cask metadata powered by [CaskFlow](https://github.com/alielsokary/CaskFlow)

## Contributing

Bug reports, taxonomy corrections, tests, documentation improvements, and pipeline hardening are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), which explains local verification, category correction evidence, and the required semantic PR title format. Pull requests target the `develop` branch.

## License

[MIT](LICENSE)

CaskFlow

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README