Il developer sthetix aggiorna HATSKit, il progetto open-source pensato per semplificare la gestione e la creazione di pacchetti personalizzati per l’ambiente HATS (Homebrew App & Tool Store) su Nintendo Switch.

Si tratta di uno strumento software a riga di comando (CLI) scritto in Python, ideato per chi possiede una console moddata e desidera organizzare in modo efficiente i propri tool, homebrew, patch e payload in un unico pacchetto installabile.

Non è un kit hardware, ma un tool software puro che permette di costruire un archivio completo e personalizzato partendo da una versione standard di HATS.

Attraverso un’interfaccia testuale interattiva, l’utente può navigare tra diverse categorie di contenuti — come applicazioni essenziali, homebrew, patch di sistema, overlay Tesla e payload di avvio — e selezionare solo ciò che desidera includere nel proprio pacchetto.

Il programma provvede a scaricare automaticamente le ultime versioni dei file dalle repository GitHub, anche da quelli privati nel caso si utilizzi un Personal Access Token (PAT), evitando così i limiti di accesso imposti dall’API pubblica.

HATSKit è inoltre dotato di un sistema di caching intelligente che riduce il numero di richieste ai server, velocizzando il processo e garantendo che le informazioni restino aggiornate per circa dodici ore.

Include inoltre un editor integrato che consente di modificare, aggiungere o eliminare componenti dal file components.json, semplificando la personalizzazione dei pacchetti.

Una volta definite le scelte, il programma avvia il processo di build, combinando automaticamente i file e generando un archivio ZIP finale (HATS_Pack_Custom.zip) pronto per essere copiato nella scheda SD della console. Viene prodotto anche un report dettagliato che elenca tutti i contenuti inclusi nel pacchetto.

Il progetto è scritto in Python 3 e si appoggia a librerie come requests, questionary e rich. Per chi preferisce un approccio più immediato, nella repository è disponibile anche una versione eseguibile per Windows (HATSKit.exe), che non richiede configurazioni aggiuntive.

Gli utenti più esperti possono persino creare un proprio eseguibile personalizzato con PyInstaller, seguendo le istruzioni presenti nel file README del progetto.

L’utilizzo è semplice: si avvia il programma, si seleziona l’opzione “Load the HATS Pack Builder”, si inserisce eventualmente il PAT di GitHub e si scelgono i componenti desiderati.

In pochi minuti il tool compila il pacchetto completo e lo rende pronto per l’installazione, compatibile con il Custom Firmware (CFW) Atmosphere. Per aggiornare i dati o risolvere problemi di caching, è disponibile il comando --clear-cache da riga di comando.

Installazione di HATSKit

Opzione 1: Download e avvio (consigliata)

Scaricare i file necessari:

• hatskit.py (per Python) oppure HATSKit.exe (per Windows).
• skeleton.zip
• components.json
• languages.zip

Posizionarere tutti i file nella stessa cartella ed estrarre l’archivio languages.zip. Successivamente eseguire il tool:

• Python: python hatskit.py
• Windows: fare doppio clic su HATSKit.exe

Opzione 2: Creazione dell’eseguibile con PyInstaller

Installare PyInstaller con il comando:

pip install pyinstaller

Creare l’eseguibile:

pyinstaller --onefile --name HATSkit --noupx --clean --add-data "components.json;." --add-data "skeleton.zip;." --add-data "languages;languages" --icon icon.ico hatskit.py

pyinstaller --onefile --windowed --name "Language Editor" --noupx --hidden-import googletrans --hidden-import httpx --icon lang.ico translate_json.py

L’eseguibile verrà creato automaticamente nella cartella dist/.

Token Personale GitHub (PAT)

Per evitare i limiti API di GitHub e per accedere alle repository private, è necessario creare un token personale.

Creazione di un token fine-grained (consigliata)

Accedere a GitHub Settings → Personal Access Tokens, selezionare Generate new token → Fine-grained personal access token e configurare come segue:

• Scadenza: Scegliere la durata preferita.
• Accesso ai repository: Selezionare “Public Repositories” o i repository specifici.
• Permessi: Impostare Contents e Metadata su “Read”.

Dopo la creazione, copiare immediatamente il token e inserirlo in HATSKit quando richiesto.

Creazione di un token classico (alternativa)

Accedere a GitHub Settings → Personal Access Tokens → Tokens (classic) e selezionare Generate new token. Abilitare gli scope richiesti:

• public_repo per repository pubblici.
• repo per repository privati.

Conservare il token in modo sicuro e non condividerlo mai pubblicamente.

Utilizzo

Menu principale

Le opzioni principali comprendono:

• Load the HATS Pack Builder: Seleziona i componenti e genera un pacchetto personalizzato.
• Load the Component Editor: Aggiunge, modifica o elimina i componenti.
• Clear Cache: forza l’aggiornamento dei dati GitHub.
• Clear GitHub PAT: rimozione del token memorizzato.

Creazione di un pacchetto personalizzato

• Avviare HATSKit, selezionare “Load the HATS Pack Builder”, inserire il token PAT (opzionale ma consigliato), attendere il caricamento e scegliere i componenti desiderati.
• Utilizzare le frecce per navigare, la barra spaziatrice per selezionare o deselezionare, il tasto a per selezionare tutto e i per invertire la selezione.
• Premere Invio per confermare e attendere la fine della build. Il pacchetto generato sarà salvato come HATS_Pack_Custom.zip.

Categorie dei componenti

• Essential (componenti di base).
• Homebrew Apps (giochi e applicazioni).
• Patches (modifiche di sistema).
• Tesla Overlays (interfacce grafiche).
• Payloads (strumenti di avvio).

Configurazione e struttura dei componenti

Esempio di struttura components.json:

{
  "component_id": {
    "name": "Component Name",
    "description": "Descrizione componente",
    "category": "Essential",
    "default": true,
    "source_type": "github_release",
    "repo": "user/repository",
    "tag": "v1.0.0",
    "asset_pattern": "*.zip",
    "processing_steps": [
      {"action": "unzip_to_root"}
    ]
  }
}

Tipi di operazioni supportate

Il tool consente di eseguire automaticamente operazioni come l’estrazione, la copia, la rinomina o l’eliminazione dei file secondo le istruzioni definite nel file JSON. Sono supportate azioni come unzip_to_root, copy_file, find_and_copy, find_and_rename e delete_file.

Opzioni da riga di comando

python hatskit.py --clear-cache

HATSkit.exe --clear-cache

File di output

Il tool genera automaticamente:

• HATS_Pack_Custom.zip (pacchetto finale),
• HATS_Pack_Contents.txt (report dettagliato),
• hats_pack_cache.json (cache API),
• components.json.bak (backup di sicurezza).

Risoluzione dei problemi

Gli errori più comuni includono limiti API, repository rimossi, file mancanti o permessi insufficienti. In tali casi, utilizzare un token PAT, verificare i percorsi dei file o eseguire il programma con privilegi amministrativi.

Gestione cache

Il file di cache hats_pack_cache.json conserva i dati delle API GitHub per 12 ore. È possibile forzare il refresh tramite l’opzione “Clear Cache” o con il parametro --clear-cache.

Contributi e licenza

Per aggiungere nuovi componenti, utilizzare l’editor integrato, testare attentamente le configurazioni e condividerle con la community. HATSKit viene fornito a scopo educativo e personale. Si raccomanda di rispettare le licenze dei singoli homebrew e delle repository GitHub utilizzate.

Supporto

Consultare la sezione Issues della repository GitHub per assistenza, verificare la sintassi JSON e assicurarsi che tutti i file necessari siano presenti. In caso di limiti API, utilizzare un token PAT valido per migliorare la stabilità del tool.

Changelog

Questa versione introduce un nuovo e potente sistema Component Uninstall Manifest e semplifica il processo di distribuzione con l’installazione automatizzata delle dipendenze.

Punti salienti principali

Nuovo metodo di installazione

• Scaricare il pacchetto ZIP completo ed estrarlo in una cartella a scelta
• Il launcher Python (launch.bat o launch.sh) eseguirà automaticamente le seguenti operazioni:
  • Verificherà se Python è installato sul sistema.
  • Installerà automaticamente Python se non presente.
  • Controllerà e installerà tutte le dipendenze necessarie.
• .NET Runtime è richiesto per utilizzare l’Editor delle lingue.
  • Se non viene rilevato, l’installer proporrà di scaricarlo.
  • Si aprirà una finestra del browser con la pagina ufficiale di download Microsoft.

Tema scuro dell’editor di lingue (nuovo!)

• L’Editor delle lingue ora presenta un elegante tema scuro in linea con lo stile visivo di HATSKit.
• Migliorata la leggibilità grazie al testo ad alto contrasto e agli accenti di colore ciano/arancione.
• Interfaccia e esperienza utente uniformi tra entrambe le applicazioni.
• Ridotto l’affaticamento visivo durante le lunghe sessioni di traduzione.

Component Uninstall Manifest (nuovo!)

• Ogni build ora genera un file HATS-MANIFEST.json all’interno dell’archivio ZIP di output.
• Questo manifest tiene traccia esatta dei file aggiunti da ciascun componente.
• Progettato per essere utilizzato con il futuro strumento HATSKit Uninstaller.
• I componenti protetti (Atmosphere, Hekate) sono esclusi dal tracciamento per evitare la rimozione accidentale di file di sistema.
• Il manifest include:
  • Nomi e versioni dei componenti.
  • Percorsi dei file per ciascun componente.
  • Metadati della build (data, versione del builder, hash dei contenuti).
  • Informazioni sulla categoria.

Esempio di caso d’uso: Se si intende rimuovere una specifica app homebrew o un overlay dalla scheda SD, il futuro strumento di disinstallazione leggerà questo manifesto e rimuoverà in modo sicuro solo i file associati a quel componente, lasciando tutto il resto intatto.

Miglioramenti tecnici

Miglioramenti del processo di compilazione

• Migliorato il tracciamento dei file durante l’elaborazione dei componenti.
• Rilevamento più intelligente tra file nuovi e modificati.
• Generazione del manifest integrata nella pipeline di build.
• Il riepilogo della build ora mostra quanti componenti vengono tracciati.

Stabilità e compatibilità

• Corretta la logica di confronto delle versioni per il rilevamento degli aggiornamenti dei componenti.
• Migliorata la gestione dei formati legacy di last_build.json.
• Migliorati i messaggi di errore e il feedback all’utente durante l’intero processo di build.

Aggiornamento dalla versione 1.0.4

• Il file config.json esistente (incluso il token GitHub salvato) verrà conservato.
• Le personalizzazioni del file components.json rimarranno intatte.
• Le build precedenti contenute in last_build.json sono completamente compatibili.
• È sufficiente estrarre la nuova versione nella cartella esistente (effettuare un backup preventivo se lo si desidera).

Download: HATSKit v1.0.5

Download: Source code HATSKit v1.0.5

Fonte: github.com