Dépôts

Ce qu'est un dépôt

Clink lit des packs depuis des dépôts GitHub publics. Vous en ajoutez un par son nom, Clink lit sa dernière version publiée, et chaque fichier est vérifié avant d'être installé. Rien n'est envoyé, et rien de ce qui vous appartient ne s'exécute sur un serveur.

Saisis owner/repository, github.com/owner/repository ou l’URL HTTPS complète. Clink vérifie chaque manifeste et chaque fichier de version avant tout téléchargement.

Choisissez un type

Chaque type de pack a son extension de fichier et son nom de collection dans le manifeste, et Clink applique à chacun sa propre limite de taille. Choisissez la ligne que vous publiez et tenez-vous-y : un thème rangé sous les panneaux n'est tout simplement pas lu.

Les packs de langue font exception. Un pack y est un ensemble de fichiers de lexique et de modèles plutôt qu'un seul document, et le dépôt officiel embarque la chaîne d'outils qui les construit. Commencez par son README plutôt que par cette page.

Partez du dépôt officiel

Le plus rapide est un fork. Il arrive avec le dossier de packs, le générateur de manifeste et le workflow de publication déjà reliés, plus des exemples qui fonctionnent et se copient.

# 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

Gardez tools/ et .github/workflows/. Ce sont eux qui transforment un push en une version que Clink sait lire ; un fork sans eux ne publie rien.

Ou construisez-le avec trois fichiers

Un dépôt n'a rien de particulier. Il lui faut un dossier de packs, un script qui écrit le manifeste et un workflow qui publie la version.

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

Le workflow fait trois choses : reconstruire le manifeste, supprimer la version précédente, et en publier une nouvelle étiquetée latest, avec les fichiers de pack et le manifeste attachés. C'est tout.

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 }}" }

Le générateur parcourt le dossier et écrit une entrée par fichier. C'est le seul endroit d'où viennent l'empreinte et le nombre d'octets : voilà pourquoi il tourne dans le workflow et non à la main.

#!/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))

Le manifeste

Chaque version publie manifest.json à côté des fichiers du pack, et Clink le lit depuis la dernière version à l'adresse https://github.com/<owner>/<repository>/releases/latest/download/manifest.json. Chaque entrée nomme le fichier, son adresse dans cette même version, son empreinte SHA-256 et son nombre exact d'octets.

{
  "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
      }
    }
  ]
}

Le nom de la collection doit correspondre au type. Les panneaux vont sous panels, les thèmes sous themes, et ainsi de suite dans tout le tableau ci-dessus.

Essayez avant de publier

Un pack dans un dépôt est le même fichier que vous pouvez ouvrir à la main : testez-le d'abord par le chemin court, en l'envoyant par AirDrop sur votre téléphone, ou en le posant dans Fichiers et en l'ouvrant avec Clink. Vérifiez ensuite le manifeste que votre script écrit.

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

1. Lancez le générateur. Il réécrit manifest.json à partir de ce que contient le dossier à cet instant.
2. Lisez ce qu'il a écrit. Chaque entrée doit nommer un fichier réellement présent, avec un nombre d'octets qui correspond.
3. Ouvrez le fichier du pack lui-même dans Clink et servez-vous-en. Un panneau ou une action atterrit dans son éditeur, où vous pouvez l'exécuter.

Publier

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

Poussez sur main et le workflow prend le relais. Il remplace la version latest au lieu de s'y ajouter : le dernier push est donc toujours ce que les autres reçoivent.

Ouvre cet onglet une fois que le dépôt a publié une version.

Ajoutez-le dans Clink

1. Ouvrez Général, puis Dépôts, et ajoutez propriétaire/dépôt.
2. Ouvrez l'onglet de votre type et tirez pour actualiser. Vos packs y figurent sous les noms que leur donne le manifeste.
3. Touchez-en un pour le télécharger. Clink le vérifie, puis l'installe comme n'importe quel autre pack.

Ajouter un dépôt suffit pour les packs de données : thèmes, dispositions, profils, sons, polices et langues. Les panneaux, les actions et les plugins contiennent de la logique, donc chaque dépôt a besoin d'un interrupteur à lui avant que Clink n'en installe un, et l'app le demande la première fois.

Les panneaux exécutent une logique interactive encadrée. N’autorise que les dépôts auxquels tu fais confiance.

Ce que Clink vérifie

1. L'adresse est en HTTPS sur github.com, dans les versions du dépôt que vous avez ajouté.
2. Le téléchargement fait exactement le nombre d'octets du manifeste, et son empreinte SHA-256 de 64 caractères correspond.
3. Le fichier porte la bonne extension et se décode comme le type de pack qu'il prétend être.
4. Les panneaux, les actions et les plugins passent la politique de source avant d'être enregistrés.

Quand un téléchargement est refusé, c'est l'une de ces cinq raisons. Le message dans l'app est volontairement court : vérifiez-les dans l'ordre.

Mettre à jour, et retirer

L'identifiant est le nom du fichier sans son extension, et c'est lui qui fait qu'une mise à jour en est une. Gardez le nom et une nouvelle version remplace la copie déjà installée. Renommez le fichier et vous avez publié un second pack à côté du premier.

Retirer un pack du dépôt arrête les nouveaux téléchargements. Cela n'atteint pas les téléphones qui l'ont déjà : traitez une mauvaise version comme une chose à remplacer, pas à supprimer.

Dépôts officiels

Forkez l'un d'eux pour commencer. Chacun construit son propre manifeste et se publie avec GitHub Actions.