Repository

Che cos'è un repository

Clink legge i pacchetti da repository GitHub pubblici. Ne aggiungi uno per nome, Clink legge la sua ultima release e ogni file viene verificato prima dell'installazione. Non viene caricato nulla e niente di tuo gira su un server.

Inserisci owner/repository, github.com/owner/repository o l’URL HTTPS completo. Clink verifica ogni manifest di release e ogni file prima di consentire qualsiasi download.

Scegli un tipo

Ogni tipo di pacchetto ha la sua estensione e il suo nome di raccolta dentro il manifest, e Clink applica a ciascuno il proprio limite di dimensione. Scegli la riga che stai pubblicando e restaci: un tema archiviato sotto i pannelli semplicemente non viene letto.

I pacchetti lingua sono l'eccezione. Lì un pacchetto è un insieme di file di lessico e modelli, non un singolo documento, e il repository ufficiale porta con sé gli strumenti che li costruiscono. Parti dal suo README invece che da questa pagina.

Parti dal repository ufficiale

La via più rapida è un fork. Arriva con la cartella dei pacchetti, il generatore del manifest e il workflow di pubblicazione già collegati, più esempi funzionanti da copiare.

# Everything a repository needs is already wired together in the official one.
gh repo fork anti-ltd/clink-panels --clone
cd clink-panels

# Your packs replace the examples. Keep tools/ and .github/.
rm Panels/*.clinkpanel
cp ~/Downloads/my-panel.clinkpanel Panels/kaomoji-plus.clinkpanel

Tieni tools/ e .github/workflows/. Sono loro a trasformare un push in una release che Clink sa leggere, e un fork senza di loro non pubblica nulla.

Oppure costruiscilo con tre file

Un repository non ha nulla di speciale. Gli servono una cartella di pacchetti, uno script che scriva il manifest e un workflow che pubblichi la release.

my-panels/
├── Panels/
│   └── kaomoji.clinkpanel        # one file per pack, the name is the id
├── tools/
│   └── build-manifest.py         # writes manifest.json from that folder
└── .github/workflows/
    └── release.yml               # turns a push into a release

Il workflow fa tre cose: ricostruisce il manifest, cancella la release precedente e ne pubblica una nuova con l'etichetta latest, con i file dei pacchetti e il manifest allegati. Tutto qui.

name: Release panels
on:
  push:
    branches: [main]
    paths: ["Panels/**", "tools/**", ".github/workflows/release.yml"]
permissions: { contents: write }
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python3 tools/build-manifest.py
      - run: gh release delete latest --yes || true
        env: { GH_TOKEN: "${{ github.token }}" }
      - run: gh release create latest Panels/*.clinkpanel manifest.json --title "Latest panels" --latest
        env: { GH_TOKEN: "${{ github.token }}" }

Il generatore percorre la cartella e scrive una voce per file. È l'unico posto da cui arrivano l'hash e il conteggio dei byte, ed è per questo che gira nel workflow e non a mano.

#!/usr/bin/env python3
import hashlib, json, os, pathlib

root = pathlib.Path(__file__).resolve().parents[1]
repository = os.environ.get("GITHUB_REPOSITORY", "<owner>/<repository>")
packs = []
for path in sorted((root / "Panels").glob("*.clinkpanel")):
    data = path.read_bytes()
    pack = json.loads(data)
    packs.append({
        "id": path.stem,
        "name": pack["name"],
        "version": "latest",
        "asset": {
            "path": path.name,
            "url": f"https://github.com/{repository}/releases/download/latest/{path.name}",
            "sha256": hashlib.sha256(data).hexdigest(),
            "byteCount": len(data),
        },
    })
(root / "manifest.json").write_text(json.dumps({"version": "latest", "panels": packs}, indent=2))

Il manifest

Ogni release pubblica manifest.json accanto ai file del pacchetto, e Clink lo legge dall'ultima release all'indirizzo https://github.com/<owner>/<repository>/releases/latest/download/manifest.json. Ogni voce indica il file, il suo indirizzo dentro la stessa release, il suo hash SHA-256 e il conteggio esatto dei byte.

{
  "version": "latest",
  "panels": [
    {
      "id": "kaomoji",
      "name": "Kaomoji",
      "version": "latest",
      "asset": {
        "path": "kaomoji.clinkpanel",
        "url": "https://github.com/<owner>/<repository>/releases/download/latest/kaomoji.clinkpanel",
        "sha256": "8f14e45fce…",
        "byteCount": 2048
      }
    }
  ]
}

Il nome della raccolta deve corrispondere al tipo. I pannelli stanno sotto panels, i temi sotto themes, e così via lungo la tabella qui sopra.

Provalo prima di pubblicare

Un pacchetto in un repository è lo stesso file che puoi aprire a mano, quindi provalo prima per la via breve: mandalo al telefono con AirDrop, oppure mettilo in File e aprilo con Clink. Poi controlla il manifest che scrive il tuo script.

python3 tools/build-manifest.py
cat manifest.json

1. Esegui il generatore. Riscrive manifest.json a partire da quello che c'è nella cartella in quel momento.
2. Leggi quello che ha scritto. Ogni voce deve nominare un file che esiste davvero, con un conteggio di byte che corrisponde.
3. Apri il file del pacchetto in Clink e usalo. Un pannello o un'azione finiscono nel proprio editor, dove puoi eseguirli.

Pubblicare

git add Panels manifest.json
git commit -m "Add my first panel"
git push

Fai push su main e il workflow prende il comando. Sostituisce la release latest invece di aggiungersi, quindi l'ultimo push è sempre ciò che ricevono gli altri.

Apri questa scheda dopo che il repository ha pubblicato una release.

Aggiungilo in Clink

1. Apri Generali, poi Repository, e aggiungi proprietario/repository.
2. Apri la scheda del tuo tipo e tira per aggiornare. I tuoi pacchetti compaiono con i nomi che gli ha dato il manifest.
3. Toccane uno per scaricarlo. Clink lo verifica e lo installa come qualsiasi altro pacchetto.

Aggiungere un repository basta per i pacchetti di dati: temi, layout, profili, suoni, font e lingue. Pannelli, azioni e plugin contengono logica, quindi ogni repository ha bisogno di un interruttore tutto suo prima che Clink ne installi uno, e l'app lo chiede la prima volta.

I pannelli contengono una logica interattiva vincolata. Consenti solo i repository di cui ti fidi.

Cosa controlla Clink

1. L'indirizzo è HTTPS su github.com, dentro le release del repository che hai aggiunto.
2. Il download ha esattamente il conteggio di byte del manifest e il suo hash SHA-256 di 64 caratteri corrisponde.
3. Il file porta l'estensione giusta e si decodifica come il tipo di pacchetto che dichiara di essere.
4. Pannelli, azioni e plugin superano la politica sul sorgente prima di essere salvati.

Quando un download viene rifiutato, è per una di queste cinque ragioni. Il messaggio nell'app è corto di proposito, quindi controllale in ordine.

Aggiornare, e ritirare qualcosa

L'id è il nome del file senza estensione, ed è ciò che rende un aggiornamento un aggiornamento. Tieni il nome e una nuova release sostituisce la copia che le persone hanno già. Rinomina il file e hai pubblicato un secondo pacchetto accanto al primo.

Togliere un pacchetto dal repository ferma i nuovi download. Non raggiunge i telefoni che ce l'hanno già, quindi tratta una release sbagliata come qualcosa da sostituire, non da cancellare.

Repository ufficiali

Fai un fork di uno di questi per cominciare. Ognuno costruisce il proprio manifest e si pubblica da sé con GitHub Actions.