awesome-core 2.0.0__py3-none-any.whl

awesome_core-2.0.0.dist-info/METADATA

@@ -0,0 +1,587 @@
+Metadata-Version: 2.4
+Name: awesome-core
+Version: 2.0.0
+Summary: Offline-first catalog of tools from GitHub awesome lists, exposed as a read-only MCP server (stdio). Pure stdlib core, no network, no API keys.
+Author: Arkadiusz Słowik
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/twojlogin/awesome-core
+Project-URL: Repository, https://github.com/twojlogin/awesome-core
+Project-URL: Issues, https://github.com/twojlogin/awesome-core/issues
+Keywords: mcp,model-context-protocol,awesome-list,offline,search,cli,sqlite
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 🔥 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: te liczby są zależne od pobranych list — nie ma tu sztywnych
+     wartości. Sprawdź aktualne: ./awesome status -->
+| | |
+|---|---|
+| narzędzi w bazie | zależne od pobranych list |
+| źródeł (repozytoriów) | zależne od pobranych list |
+
+Aktualne liczby zawsze sprawdzisz: `./awesome status`.
+
+---
+
+**Uczciwa uwaga:** nie ma tu żadnego AI. Żadne modele językowe nie wybierają,
+nie oceniają ani nie rankują narzędzi. To zwykły Python, który parsuje README
+z list GitHuba i liczy rzeczy na surowo. Jeśli liczby w README różnią się od
+bazy — ktoś zapomniał odświeżyć blok STAN. Zrób `./awesome status` i popraw.
+
+## 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-core/awesome",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Co warto wiedzieć:
+
+- **Nic nie wychodzi do sieci.** Zero kluczy API, zero kont, tylko odczyt
+  lokalnej bazy SQLite. Serwer nie ma narzędzi z efektem ubocznym.
+- **Start jest natychmiastowy** — baza jest już zbudowana, serwer tylko czyta.
+- Wyniki to zwykły tekst z liczbami (gwiazdki, liczba niezależnych list, score),
+  więc agent może je cytować i porównywać.
+- Protokół jest czystym JSON-RPC 2.0 po stdin/stdout; logi idą na stderr,
+  żeby nie psuły kanału.
+
+---
+
+## Skąd to wszystko pochodzi — i czy mi szkodzi
+
+Pytanie, które powinien zadać każdy: *co jeśli ktoś wrzuci złośliwą listę?*
+
+**Skąd listy:** `download.sh` pyta publiczne API GitHuba o repozytoria
+oznaczone `topic:awesome-list` (plus `topic:awesome` i `topic:curated-list`
+w trybie `--wide`), posortowane po gwiazdkach. Nic więcej — żadnych
+„polecanych" repozytoriów, żadnych losowych adresów.
+
+**Nic z obcego repozytorium nigdy nie jest wykonywane:**
+
+- README jest **danymi**. Parser wyciąga z niego linki regexem i tyle.
+  Nie ma miejsca, w którym treść README trafiłaby do `eval`, `exec`,
+  `shell=True` czy któregokolwiek wywołania systemowego.
+- `awesome install` robi dokładnie `git clone --depth 1`. Git nie uruchamia
+  kodu z zdalnego repozytorium (żadnych hooków).
+- Przeglądarka escapuje HTML, a renderer Markdown w `core/md.py` też —
+  `<script>` w opisie wychodzi jako tekst, nie jako tag.
+
+**Jedyny realny wektor: opisy trafiające do kontekstu modelu.** Serwer MCP
+zamienia opisy narzędzi w tekst, który czyta agent. Opis napisał ktoś
+nieznany, w repozytorium niesprawdzonym. Dlatego:
+
+- Opisy przechodzą przez `core/untrusted.py`, które wycina instrukcje
+  wyglądające na polecenia, znaczniki ról (`system:`, `assistant:`), tagi
+  HTML, `curl … | sh` i `rm -rf` — zostawiając przy tym znacznik
+  `[odfiltrowano: …]`, żeby dało się zauważyć.
+- `initialize` w MCP mówi agentowi wprost: to treść trzecia, nie rozkazy.
+- Sprawdź sam, kiedy chcesz:
+
+```bash
+./awesome untrusted
+```
+
+Stan na dziś: **0 wykrytych ataków** w 186 861 narzędziach (3 trafienia to
+fałszywe alarmy — `rimraf` ma w opisie „like rm -rf", a `safety-net` to
+narzędzie, które `rm -rf` blokuje). Ciekawa ironia: katalog zawiera trzy
+narzędzia do obrony przed dokładnie tym problemem (`nvidia/skillspector`,
+`vaporif/parry-guard`, `safety-net`).
+
+Czego **nie** obiecuję: skaner łapie znane wzorce, nie jest dowodem
+niezawodności. Dlatego traktuj opisy jako dane, a nie polecenia.
+
+---
+
+## Zasada: rdzeń bez AI
+
+Właściciel projektu dopuścił MCP, ale nie chce sztucznej inteligencji
+wszędzie — szczególnie nie w narzędziu, które miało być lokalne. Zapisuję to,
+bo obietnica bez pilnowania wyparuje się przy pierwszym refaktorze:
+
+| Warstwa | AI? | Sieć? |
+|---|---|---|
+| parser, baza, ranking, kopie, shortlist, TUI, web | **nie** | **nie** — czyste odczyty z `data/awesome.db` |
+| `core/mcp.py` (adapter dla agentów) | tak, poza procesem | nie — JSON-RPC po stdio |
+| `download`, `enrich`, `backfill`, `validate`, `install` | nie | tak, tylko na wyraźne polecenie |
+
+Z tego wynika reszta decyzji:
+
+- **Cała zależność zewnętrzna to `flask`** (web UI). Rdzeń to czysty stdlib.
+- **Zero modeli, embeddingów, sieci neuronowych czy LLM w rankingu.** Sortowanie
+  to jawna arytmetyka (`core/scoring.py`), którą da się wypisać i podważyć.
+- **Ranking nie zależy od usługi firmy trzeciej.** Nikt nie może Ci podsunąć
+  wyników ani zobaczyć, czego szukałeś.
+- **MCP jest adapterem na brzegu**, nie logiki w środku. Możesz go wywalić
+  i nic nie przestanie działać.
+- Test `test_no_ai_in_core` pilnuje tego mechanicznie: rdzeń nie zaimportuje
+  biblioteki AI ani sieciowej modułu bez zgody, a jedynym plikiem znającym
+  protokół MCP jest `core/mcp.py`.
+
+---
+
+## Czy katalog można zatruć — i co z tym robimy
+
+Katalog powstaje z **cudzych repozytoriów**. To znaczy, że ktoś może celowo
+wstawić fałszywą listę, która zbiera wejścia, a jej „narzędzia" prowadzą do
+podszywanych domen albo do szkodliwego kodu. **Czy to się zdarzyło?**
+
+```bash
+./awesome audit
+```
+
+Stan na dziś (6 października 2026, 1 032 listy, 186 861 narzędzi): **7 list
+warte obejrzenia, 1 podejrzany link**. Zero potwierdzonych ataków.
+
+Co sygnał ma złapać:
+
+| Sygnał | Dlaczego podejrzane |
+|---|---|
+| dużo narzędzi przy **0 gwiazdek** | twórca dopiero zaczął — nie ma reputacji do stracenia |
+| **jeden właściciel** dla wielu linków | to nie katalog, tylko linki do jednego projektu |
+| dużo **martwych linków** | farma linków, nie treść |
+| niedawno utworzone repo + dużo narzędzi | kampania, nie dorobek |
+| **klon** innej listy | kopiowanie zamiast budowania |
+| link typu `github.com@evil.tld`, `githvb.com`, adres IP, punycode | podszywanie domeny |
+
+Przykładowe trafienie z naszej bazy: `laoma2053/awesome-zhuiju-free` — 25 narzędzi,
+**0 gwiazdek**, brak opisu, żaden link nie potwierdzony przez inną listę.
+
+Czego **nie** robimy i dlaczego warto to wiedzieć:
+
+- **To nie jest skaner złośliwego oprogramowania.** Nie rozpoznajemy droppera
+  w repozytorium ani złośliwego kodu w kodzie narzędzia. Nie obiecujemy, że
+  przepuścimy wszystko.
+- **Sygnały nie są wyrokiem.** Flag oznacza „obejrzyć ręcznie", nie „złośliwe".
+  Trzy z siedmiu trafień okazały się uczciwymi, choć dziwnymi listami.
+- **Ranking już się przed tym broni**: narzędzie potrzebuje zgody co najmniej
+  dwóch niezależnych list, a kopie list nie liczą się do tej zgody. Jedna
+  nowa fałszywa lista nie wypchnie niczego na szczyt.
+- **`awesome install` to tylko `git clone`.** Nie uruchamia skryptów, nie pyta
+  o hasło do Twojego GitHuba, nie wykonuje kodu zdalnego repozytorium. Ale
+  potem **to Ty** decydujesz, co z tym kodem zrobisz — i tego program nie
+  kontroluje.
+- **Opisy z obcych list trafiają do kontekstu modelu przez MCP**, więc są
+  przepuszczane przez `core/untrusted.py` (patrz sekcja o bezpieczeństwie).
+
+Najprostsza zasada: narzędzie z jednej nowej listy, o którym nigdy nie
+słyszałeś, to znak sprawdzenia — nie polecenia instalacji.
+
+---
+
+## Czego nie wiem — słowniczek
+
+| Słowo | Co to znaczy |
+|---|---|
+| **awesome list** | lista linków do narzędzi prowadzona na GitHubie (np. `sindresorhus/awesome`) |
+| **baza (SQLite)** | jeden plik `data/awesome.db` z całym katalogiem; zwykły plik, możesz go skasować i przebudować. Kasowanie i wstawianie idą w jednej transakcji, więc przerwany build zostawia poprzednią bazę, a nie pustą |
+| **FTS5** | wbudowany w SQLite szybki indeks tekstowy — dzięki niemu szukanie trwa milisekundy |
+| **metadane listy** | gwiazdki, język, opis listy z GitHuba |
+| **metadane narzędzia** | gwiazdki, język i czy żyje repozytorium **samego narzędzia** |
+| **consensus (zgoda)** | narzędzie wskazane przez ilu **różnych** autorów list — nasz główny ranking |
+| **jakość listy** | 0–1: czy lista ma opisy, czy duplikaty, czy jej linki żyją, czy jest aktualna |
+| **score** | punkty narzędzia (0–100) z tych wszystkich sygnałów |
+
+**Program niczego nie rekomenduje.** Nie ma w nim „polecam", „najlepszy wybór"
+ani LLM, który podpowiada narzędzia. Jest za to: policzone liczby (zgoda
+niezależnych kuratorów, gwiazdki, jakość listy, z jakich list narzędzie
+pochodzi) i filtry o jawnych kryteriach. Wybór zostaje po Twojej stronie —
+dlatego wszystko, co program mówi, da się sprawdzić liczbą.
+| **backfill** | dociąganie brakujących metadanych list |
+| **enrich** | sprawdzanie repozytoriów narzędzi (batch po 50 na zapytanie do API) |
+| **build** | przebudowa bazy z lokalnych plików README (~2 min) |
+| **fasetka** | klikalny filtr boczny, np. „język: Python” |
+
+---
+
+## Licencja
+
+MIT — `LICENSE` w katalogu. Kod jest mój, ale **nazwy, linki i krótkie opisy
+narzędzi pochodzą z cudzych awesome list** i należą do ich autorów. W bazie
+są tylko adresy i nazwy repozytoriów (fakty, nie czyjeś treści), a same
+README nie są dołączane do repo — pobierasz je na swój dysk przez
+`./download.sh`.
+
+## Znane ograniczenia (uczciwie)
+
+**Ranking czyta to, co napisał autor — nie kod.** Nazwa, opis, gwiazdki,
+tematy, README: wszystko to można napisać dowolnie i wszystko wchodzi do
+score. Program **nigdy nie zagląda do kodu repozytorium**, więc nie odróżnia
+narzędzia od kolekcji skryptów o tej samej nazwie ani oryginału od kopii.
+
+Mierzalny skutek: `awesome selfcheck` sprawdza 15 znanych narzędzi
+(nazwa → właściwe repozytorium) i zwykle trafia **13/15 na pozycji #1**.
+Dwie porażki to zawsze ten sam mechanizm — repozytorium fanowskie, które
+powtarza nazwę narzędzia w opisie, wyprzedza oryginał.
+
+```bash
+./awesome selfcheck
+```
+
+To jest granica tego podejścia, nie do poprawienia strojeniem wag: do jej
+przekroczenia trzeba by patrzeć na zawartość repozytorium (importy, pliki
+wejściowe, tagi wydań), a to osobny projekt. Świadomie tego nie udaję.
+
+**Mniej poważne, ale też powiedziane:**
+- 91% narzędzi występuje w jednej liście, więc dla nich „zgoda kuratorów"
+  wynosi zero — teza działa na głowie katalogu, nie na ogonie
+- 75 571 wpisów to linki poza GitHubem (artykuły, filmy, dokumentacja):
+  nigdy nie dostaną gwiazdek i nie są narzędziami
+
+* **Wyszukiwarka GitHuba oddaje maks. 1000 wyników na jedno zapytanie.**
+  Dlatego pobieranie używa kilku zapytań naraz (`--wide`) i skaluje wyniki.
+* **Prawdziwy język narzędzia** znamy tylko dla repozytoriów sprawdzonych przez
+  `./awesome enrich`. Reszta zgadywana jest z adresu i opisu — stąd `?` tam,
+  gdzie nie wiadomo. Ranking celowo nie ufa temu zgadywaniu.
+* **Linki poza GitHubem** sprawdzamy tylko na żądanie:
+  `./awesome validate --non-github --limit 500`.
+* **Nie sprawdzamy, czy narzędzie jest bezpieczne.** Sygnały przy repozytoriach
+  (archiwalne, dawno nieaktualizowane) to wskazówki do sprawdzenia, nie etykieta.
+  Przeczytaj kod i release'y, zanim cokolwiek zainstalujesz.
+
+---
+
+## Dla tych, którzy chcą wejść głębiej
+
+<details>
+<summary>Struktura projektu</summary>
+
+```
+awesome              # wygodny wrapper: ./awesome <komenda>
+download.sh          # pobieranie README list z GitHuba (bash + gh + jq)
+extract_tools.py     # budowa bazy z lokalnych README
+data/awesome.db      # baza SQLite (generowana, w .gitignore)
+offline-db/          # pobrane README list (generowane, w .gitignore)
+
+core/store.py        # schemat bazy, migracje, zapis metadanych
+core/parser.py       # wyciąganie narzędzi z markdown (listy i tabele)
+core/langmap.py      # język / platforma / domena / czyszczenie URL-i
+core/scoring.py      # consensus, jakość listy, ranking
+core/aliases.py      # synonimy („port scanner” → nmap, masscan…)
+core/md.py           # własny renderer Markdown → HTML (bez CDN)
+core/builder.py      # orkiestracja builda
+core/backfill.py     # metadane list
+core/enrich.py       # metadane repozytoriów narzędzi
+core/status.py       # stan danych i plan odświeżenia
+core/tools_db.py     # zapytania (search, fasetki, ranking)
+core/database.py     # zapytania po listach/repozytoriach
+core/curator.py      # kolekcje + instalacja
+core/validator.py    # weryfikacja linków
+core/trust.py        # sygnały ryzyka przy repozytoriach
+cli/awesome_cli.py   # CLI
+cli/tui.py           # TUI (curses)
+web/app.py           # Flask UI
+web/templates/       # szablony Jinja2
+tests/smoke_test.py  # 106 testy (CI)
+```
+
+</details>
+
+<details>
+<summary>Jak liczymy ranking</summary>
+
+`score` (0–100) to świadoma korekta nad „sortuj po gwiazdkach listy”:
+
+| Składowa | Waga | Znaczenie |
+|---|---|---|
+| `consensus` | 0.28 | w ilu **niezależnych** listach jest narzędzie × jakość tych list |
+| `own_stars` | 0.22 | gwiazdki **samego narzędzia** (z API), nie listy |
+| `quality` | 0.14 | jakość listy: opisy, unikalność, żywe linki, świeżość, rozmiar |
+| `alive` | 0.14 | link sprawdzony i żywy |
+| `desc` | 0.10 | ma sensowny opis |
+| `list_stars` | 0.06 | gwiazdki listy (słaby sygnał) |
+| `known` | 0.06 | mamy metadane narzędzia z API |
+
+Dodatkowo `underrated` (dobra jakość, mało gwiazdek) i `hidden_gem` (mało list,
+wysoki score). `./awesome why <nazwa>` pokazuje rozkład punktów.
+
+</details>
+
+<details>
+<summary>Wymagania i licencja</summary>
+
+* Python 3.8+ (SQLite z FTS5; bez FTS5 działa fallback na LIKE)
+* Flask ≥ 3.0 — tylko dla web UI
+* `gh`, `jq`, `curl` — tylko do pobierania i enrichmentu
+* `curses` z biblioteki standardowej — tylko dla TUI
+
+MIT — używaj, zmieniaj, dziel się.
+Autor: **Arkadiusz Słowik** — [@twojlogin](https://github.com/twojlogin)
+
+</details>

awesome_core-2.0.0.dist-info/RECORD

@@ -0,0 +1,33 @@
+awesome_core-2.0.0.dist-info/licenses/LICENSE,sha256=otBwht3mJ1u0kxyI-tUPAPXjGpo34AZjZ0lxvomhO_8,1061
+core/__init__.py,sha256=VjE4x2psjrINSAaRLbZqS6vuoke53N9X_HmqcFOarYI,50
+core/aliases.py,sha256=a3TcOGo7gG3ee1EPTN3rqEBQHW1MYCimIEdV7mJznUI,7759
+core/api.py,sha256=-U67VsQT2h0qHt0v_Va9V89AjZL2jjKCQum01gUaTLU,6001
+core/backfill.py,sha256=TKXt5F_RXHvjuJqNMHZ8j4DuIuij-_tfix5IxmoTv4g,8347
+core/bootstrap.py,sha256=1RWQjuvpraK5Izp1TPWULWqT8ZGw_R5N-7_D3nelIpE,3953
+core/builder.py,sha256=6guHkeu-pmAJN84Dt9dqx4J3roqXqPTNvxI9nwk-qEw,19892
+core/clones.py,sha256=LhwEPMWbrTc7vuRvVsU_HiknoEyLx5v-9uC0PZbVq2s,6286
+core/curator.py,sha256=LHrfZymI6vvG0XXX9DZQ6emYH5CB1_llACC7NvNlNng,8736
+core/database.py,sha256=TAydogfMIM-B1E72BxJqC2SuaHhoQxCack-19PHU4Cg,6388
+core/doctor.py,sha256=lYkcX47iDKkvgJ4jAYDCOxnGbGGDy3M3aXKEx41NEKg,4625
+core/enrich.py,sha256=j60vUKRyTFW0w8swHwcU5oyW20KZXcX6-P6AEbX5URY,11878
+core/fetcher.py,sha256=LfrCUPetJD6xUrWPNzMOI793Nggqrcq9vsklykwuyII,7867
+core/langmap.py,sha256=qqoIWtjdUrLwZMBzWRPCwAVIjMYShc_3GmFTNYCK79Q,26233
+core/mcp.py,sha256=oE1fIOF3QEBozrhrmMb86teKc8YDuo-_2FkFm164_8U,19272
+core/md.py,sha256=VJBBSr4pS7JJn9ekmviasX8YcsOZR73LeXWR5c_EVsA,15345
+core/parser.py,sha256=d4TGNxmmBDF5hxACXzrZ0Y43fw1pzVU-xX69q1HLBCo,8525
+core/poisoning.py,sha256=qHXpYE-lvLD1tLm8aBOuCVQqBKcks0CzQg7lZvYHJkU,7899
+core/scoring.py,sha256=pUQpVVUy9-u-PIAs9gISSeWLB2uTxxXlscLaT-ysGGI,6128
+core/selfcheck.py,sha256=PU5dgdMTfA8IPjUAuzG48Fovf8TPuM9h3AgQasVtzCU,2217
+core/shortlist.py,sha256=xtTIn6pCNJw20iWLr3P5jUt0YwMG0J2MWLfYJs7SbX0,6265
+core/status.py,sha256=hPs2r6JH7J9TVgX6UFro6mitFmRy1NGZPSHj2VIiR7g,7168
+core/store.py,sha256=H7_pPQbVCEF7QDooTHwoPwyPDAMza57eaCsjqgTMzuc,17638
+core/tools_db.py,sha256=hJm_eGAspMJo0br_FkW9lBrE1v3mawXmQXjI9Z_BSFE,30813
+core/trust.py,sha256=hxrGgT_L2AGoJZss-x0siP4OO1g3Wm7FRTph6zRJrLY,4383
+core/untrusted.py,sha256=dU7SDYTbAMjTMZ_MAonkM_HT0vzzRNdkJfPKpr4hNFc,4148
+core/validator.py,sha256=p49ARubiIuctThdiRfMfkyxs9MutYNQ5o9IRKSmP5S0,5470
+core/watcher.py,sha256=reJAKSHy2LcB-NZT5XHPS7W9fpGkOZ9Gi7m5sYru2bw,3108
+awesome_core-2.0.0.dist-info/METADATA,sha256=ybqh-TRlHV3IidFn7KbrM_nhZiFHL2kUExYb9xBbhhw,23842
+awesome_core-2.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+awesome_core-2.0.0.dist-info/entry_points.txt,sha256=XEK3KPcHGt_Fd_6qx1SftInuwuUhoveFFjD8R8WO9LY,47
+awesome_core-2.0.0.dist-info/top_level.txt,sha256=0ebp8k35dOTHVwbY3UcokRsjC7cWLN_iaJ70tIcmODU,5
+awesome_core-2.0.0.dist-info/RECORD,,

awesome_core-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

awesome_core-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+awesome-core = core.mcp:main

awesome_core-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

awesome_core-2.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+core

core/__init__.py

@@ -0,0 +1 @@
+from core.database import AwesomeDB  # noqa: F401