awesome-core

# 🔥 Awesome Core

## Czym to jest, w jednym zdaniu

**Ściąga wszystkie awesome listy z GitHuba do jednego katalogu na Twoim dysku
i pozwala szybko znaleźć narzędzie — po nazwie, języku, systemie albo temacie —
całkowicie bez internetu.**

Na przykład chcesz „coś do OSINT-a działające pod Windows". Wpisujesz:

```bash
./awesome search osint --os windows
```

i dostajesz narzędzia z kilku różnych awesome list naraz, posortowane tak, że
na górze są te, które **niezależni kuratorzy wskazali w wielu listach**
(a nie tylko te z jednej głośnej listy).

> **Filtry łączy AND, więc kumulują się szybko.** `--os windows --lang PowerShell`
> zostawia z „osint" **jedno** narzędzie — i to nie to, czego szukałeś, tylko
> skrypt PowerShell, który akurat też nazywa się „Sherlock". Program wie, że
> filtr jest za wąski, i mówi wprost, który odpuścić:
>
> ```
> Uwaga: 2 filtry łączy AND i zostawiły 1 wynik(ów).
>     bez lang=PowerShell  →  8 wyników
> ```
>
> Zasada: dodawaj filtr tylko wtedy, gdy wyników jest więcej niż kilka.

---

## Jeśli nie masz czasu — trzy komendy

```bash
./awesome start      # 1. wszystko robi za Ciebie (pobiera, buduje, gotowe)
./awesome search nmap
./awesome web        # i otwiera przeglądarkę
```

`./awesome start` mówi w każdym kroku, co robi i ile to potrwa. Nic działa się
samo w tle — zawsze widzisz postęp.

---

## Co musisz mieć zanim zaczniesz

**Jedna rzecz: Python 3.8 lub nowszy.** To wszystko.

| Potrzebujesz | Po co | Sprawdzenie |
|---|---|---|
| **Python 3.8+** | program — jedyna zależność | `python3 --version` |

**Nie potrzebujesz** jq, curl, GitHub CLI ani samodzielnego `python -m venv`:

- pobieranie list działa przez zwykły HTTPS (`core/api.py`) — bez `gh` jest
  wolniej, bo GitHub limituje wyszukiwanie do 10 zapytań na minutę, ale działa;
- Flask do web UI instaluje się sam przy pierwszym `./awesome web`;
- program sam mówi, gdy brakuje czegoś (`./awesome doctor`).

Jeśli masz `gh` i się zalogujesz (`gh auth login`), wszystko idzie 30× szybciej
i `enrich` w ogóle się odblokuje. Ale to przyspieszenie, nie warunek.

Instalacja na Linuksie:

```bash
sudo apt install python3               # albo: sudo dnf install python3
```

Opcjonalnie, dla 30× szybszego pobierania i metadanych narzędzi:

```bash
gh auth login                          # GitHub CLI, jednorazowo
```

**Windows działa bez basha.** W katalogu jest `awesome.cmd`, więc w PowerShellu
albo po podwójnym kliknięciu piszesz po prostu:

```powershell
awesome.cmd start
awesome.cmd web
```

`download.sh` został, ale to już tylko nakładka wywołująca Pythona — w nim nie
ma już ani `jq`, ani `curl`, ani pętli w shellu.

W PowerShellu odpowiedniki reszty komend:

```powershell
gh auth login                 # potem reszta jak w Linuxie
.\venv\Scripts\Activate.ps1 # aktywacja venv
.\awesome web
```

Flask do web UI instaluje się **sam**, przy pierwszym `./awesome web`:

```
Web UI potrzebuje Flaska. Przygotowuję środowisko (requirements.txt):
  Tworzę venv…
  Aktualizuję pip…
  Instaluję z requirements.txt…
  Gotowe. Od teraz web używa venv/.
```

Jeśli z jakiegoś powodu to się nie uda (brak sieci, proxy), program wypisze
instrukcję ręczną — ale nie musisz jej pamiętać na co dzień.

**Nie musisz** znać SQL, programować, nic konfigurować w środku i **nie musisz**
nic aktualizować automatycznie. Jak coś nie działa — `./awesome status` powie
Ci, co dokładnie odpalić.

---

## Pierwsze uruchomienie, krok po kroku

### `./awesome start`

Program sprawdza, czy masz wszystko, potem:

| Krok | Co robi | Ile trwa |
|---|---|---|
| 1 | pobiera README awesome list z GitHuba (pomija to, co już masz) | 10–25 min |
| 2 | wyciąga z nich narzędzia do bazy | ~2 min |
| 3 | dociąga gwiazdki i języki list | ~1 min |
| 4 | **włącza Web UI** i czeka | — |

**Jeśli baza już jest zbudowana, `start` nie pobiera nic od nowa.** Wypisuje
liczbę narzędzi i od razu włącza interfejs. Przebudowa wymaga świadomej decyzji:

```bash
./awesome start --rebuild    # kasuje bazę i buduje od nowa (~2 min)
./awesome refresh            # dociąga brakujące dane i przebudowuje
```

Dzięki temu przypadkowe `./awesome start` nie kasuje Ci 2 minuty pracy.

**Uwaga, uczciwie:** `start` nie odpytuje GitHuba o repozytoria samych
narzędzi. Ranking od razu działa (na zgodzie kuratorów), ale gwiazdka przy
narzędziu to na razie szacunek z listy, nie prawdziwa liczba. Jedna komenda
to naprawia:

```bash
./awesome enrich      # 30–60 min, odpytuje ~35 tys. repozytoriów
./awesome build       # ~2 min, żeby gwiazdki wsiąkły do rankingu
```

Albo jednym poleceniem od zera:

```bash
./awesome start --full   # download → build → backfill → enrich → build
```

Robisz to raz. Przerwać można w każdej chwili (Ctrl+C) — postęp jest zapisywany
i odpalanie komendy drugi raz jedzie dalej. Bez zalogowania do GitHuba `enrich`
odmawia z wyjaśnieniem zamiast udawać, że zrobił swoją robotę.

Jeśli masz mało czasu, krok 1 możesz pominąć i nadrobić później:

```bash
./awesome start --skip-download     # szybka ścieżka: buduje z tego, co już jest
```

### Codzienne użycie

```bash
./awesome search "port scanner"                    # szukaj po ludzku
./awesome search osint --lang Python              # ...tylko Python
./awesome search "active directory" --os windows  # ...tylko pod Windowsa
./awesome langs                                    # co jest w bazie (języki)
./awesome platforms                                # systemy: Windows, Linux, Docker...
./awesome domains                                  # tematy: osint, security, network...
./awesome why nmap                                 # skąd ten wynik — punkt po punkcie
./awesome mentions nmap                            # w ilu listach jest to narzędzie
./awesome audit                                    # czy katalog nie jest zatruty fałszywymi listami
./awesome audit sindresorhus/awesome               # audyt jednego repozytorium
./awesome lists                                    # najlepsze listy
./awesome info nmap                                # dane + komenda instalacji
./awesome install nmap                             # zainstaluj (git clone)
```

### Twoja własna lista

Jak coś znajdziesz i działa — włóż to od razu na swoją listę, a na końcu
wklej gotowy Markdown:

```bash
./awesome shortlist add nmap --note "do skanowania sieci"
./awesome shortlist                            # co jest na liście
./awesome shortlist emit --title "Moja lista OSINT" --group domain
./awesome shortlist emit --out moja-lista.md  # zapisz do pliku
```

W web UI jest to samo: przycisk **☆ Do mojej listy** na stronie narzędzia,
lista i Markdown pod linkiem *Moja lista* w menu. W TUI klawisz `k`.

Osobno istnieje `watch` — lista **repozytoriów list**, które chcesz śledzić
(nowe narzędzia w ulubionej liście), a nie lista narzędzi:

```bash
./awesome watch add sindresorhus/awesome
./awesome watch check          # co doszło od ostatniego sprawdzenia
```

Obie listy są lokalne i żadna nie odpytuje się sama w tle.

### TUI — klawisze

```text
/  szukaj              l  następny język      o  następna platforma
d  następna domena      s  zmień sortowanie     a  wyczyść filtry
g  ukryte perełki      u  niedoceniane        Enter  szczegóły
k  do mojej listy      i  instaluj             ?  pomoc
q  wyjście
```

### Cztery interfejsy, ten sam katalog

```bash
./awesome            # terminal — najszybszy do szybkiego szukania
./awesome tui        # terminal, ale interaktywnie (strzałki, filtry)
./awesome web        # przeglądarka (port wypisuje na ekranie)
./awesome help       # wszystkie komendy
```

---

## Codzienna pielęgnacja (nic nie leci samo)

```bash
./awesome status     # co jest w bazie, kiedy ostatnio odświeżone, czego brakuje
./awesome refresh    # pobierz nowe listy → metadane → przebuduj bazę
```

`./awesome status` po odświeżeniu podpowiada dokładną komendę, np.
`./awesome enrich`. To samo w przeglądarce: strona `/refresh`
z czterema przyciskami. Żadnych cronów, daemonów ani procesów w tle.

**Ważne przy liczbach:** status nie mówi „X narzędzi bez gwiazdek", tylko ile
**repozytoriów zostało do odpytania**. Różnica jest ogromna, bo kilka narzędzi
często wskazuje na to samo repo, a linki poza GitHubem (artykuły, filmy,
dokumentacja) **nie mają i nigdy nie będą miały gwiazdek** — nie licz ich
jako brakującej pracy.

---

---

## Co jest w środku (stan z bazy)

<!-- STAN: te liczby muszą zgadzać się z ./awesome status.
     Pilnuje tego test_docs_numbers_match_database — nie edytuj ręcznie 
     popraw dane i odśwież. -->
| | |
|---|---|
| narzędzi (unikalne URL) | **187 666** |
| wzmianek w listach | **216 383** |
| list (z metadanymi) | **1 032** |
| języków | **81** |
| linki żywe / martwe | **100 868 / 9 357** |
| spoza GitHuba (bez gwiazdek z definicji) | **76 148** |
| katalog waży | **234.5 MB** |

Aktualne liczby zawsze sprawdzisz: `./awesome status`. To jest stan z 6 października
2026 — po `enrich` i pełnym przebudowaniu.

## Podłącz agenta AI (MCP) — lokalnie, bez kluczy API

Katalog można dać do dyspozycji lokalnemu agentowi (Claude, Cursor, cokolwiek
mówi „Model Context Protocol”) jako źródło narzędzi. Agent dostaje ranking
oparty o zgodę niezależnych kuratorów, a nie o to, co jest najczęściej
wypisane w jednym README.

```bash
./awesome mcp --demo    # podgląd: zobaczysz całą wymianę JSON-RPC bez agenta
./awesome mcp           # serwer czeka na stdin (tak to działa w praktyce)
```

Serwer daje 5 narzędzi: `search_tools` (szukanie z filtrami),
`find_undiscovered_tools` (niedoceniane i ukryte perełki), `explain_tool`
(uzasadnienie rankingu: z jakich list, ile punktów, co ważyło),
`lists_with_tool` (wszystkie listy + oznaczone kopie) i `catalog_facets`
(co jest w bazie: języki, platformy, domeny).

Wpisz to do konfiguracji klienta, np. `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "awesome-core": {
      "command": "/pełna/ścieżka/do/awesome-core2/awesome",
      "args": ["mcp"]
    }
  }
}
```

Co warto wiedzieć:

- **Nic nie wychodzi do sieci.*