Repositorios

Qué es un repositorio

Clink lee paquetes de repositorios públicos de GitHub. Tú añades uno por su nombre, Clink lee su última versión publicada y cada archivo se verifica antes de instalarse. No se sube nada y nada tuyo se ejecuta en un servidor.

Introduce owner/repository, github.com/owner/repository o la URL HTTPS completa. Clink verifica cada manifiesto y archivo de versión antes de permitir cualquier descarga.

Elige un tipo

Cada tipo de paquete tiene su propia extensión de archivo y su propio nombre de colección dentro del manifiesto, y Clink aplica a cada uno su propio límite de tamaño. Elige la fila que vas a publicar y respétala: un tema archivado bajo paneles sencillamente no se lee.

Los paquetes de idioma son la excepción. Ahí un paquete es un conjunto de archivos de léxico y modelos, no un único documento, y el repositorio oficial incluye las herramientas que los construyen. Empieza por su README en lugar de por esta página.

Empieza desde el repositorio oficial

La vía más rápida es un fork. Llega con la carpeta de paquetes, el generador del manifiesto y el flujo de publicación ya conectados, además de ejemplos que funcionan y puedes copiar.

# 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

Conserva tools/ y .github/workflows/. Esos dos son los que convierten un push en una versión que Clink puede leer, y un fork sin ellos no publica nada.

O créalo con tres archivos

Un repositorio no tiene nada de especial. Necesita una carpeta de paquetes, un script que escriba el manifiesto y un flujo de trabajo que publique la versión.

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

El flujo hace tres cosas: regenerar el manifiesto, borrar la versión anterior y publicar una nueva con la etiqueta latest, con los archivos de paquete y el manifiesto adjuntos. Esto es todo.

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

El generador recorre la carpeta y escribe una entrada por archivo. Es el único sitio del que salen el hash y el recuento de bytes, y por eso se ejecuta en el flujo de trabajo y no 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))

El manifiesto

Cada versión publica manifest.json junto a los archivos del paquete, y Clink lo lee de la última versión en https://github.com/<owner>/<repository>/releases/latest/download/manifest.json. Cada entrada nombra el archivo, su dirección dentro de esa misma versión, su hash SHA-256 y su recuento exacto de bytes.

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

El nombre de la colección tiene que coincidir con el tipo. Los paneles van en panels, los temas en themes, y así por toda la tabla de arriba.

Pruébalo antes de publicar

Un paquete de un repositorio es el mismo archivo que puedes abrir a mano, así que pruébalo primero por la vía corta: envíalo a tu teléfono por AirDrop, o ponlo en Archivos y ábrelo con Clink. Después revisa el manifiesto que escribe tu script.

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

1. Ejecuta el generador. Reescribe manifest.json a partir de lo que haya ahora mismo en la carpeta.
2. Lee lo que ha escrito. Cada entrada debe nombrar un archivo que exista de verdad, con un recuento de bytes que coincida.
3. Abre el propio archivo del paquete en Clink y úsalo. Un panel o una acción aterrizan en su editor, donde puedes ejecutarlos.

Publicar

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

Envía a main y el flujo de trabajo se encarga del resto. Reemplaza la versión latest en lugar de añadirse a ella, así que el último push siempre es lo que reciben los demás.

Abre esta pestaña cuando el repositorio haya publicado una versión.

Añádelo en Clink

1. Abre General, luego Repositorios, y añade propietario/repositorio.
2. Abre la pestaña de tu tipo y desliza para actualizar. Tus paquetes aparecen con los nombres que les dio el manifiesto.
3. Toca uno para descargarlo. Clink lo verifica y lo instala como cualquier otro paquete.

Añadir un repositorio basta para los paquetes de datos: temas, disposiciones, perfiles, sonidos, fuentes e idiomas. Los paneles, las acciones y los plugins llevan lógica, así que cada repositorio necesita su propio interruptor antes de que Clink instale cualquiera de ellos, y la app lo pregunta la primera vez.

Los paneles contienen una lógica interactiva restringida. Permite solo repositorios en los que confíes.

Qué comprueba Clink

1. La dirección es HTTPS en github.com, dentro de las versiones del repositorio que añadiste.
2. La descarga tiene exactamente el recuento de bytes del manifiesto y su hash SHA-256 de 64 caracteres coincide.
3. El archivo lleva la extensión correcta y se decodifica como el tipo de paquete que dice ser.
4. Los paneles, las acciones y los plugins pasan la política de código fuente antes de guardarse.

Cuando se rechaza una descarga, es por una de estas cinco razones. El mensaje de la app es corto a propósito, así que compruébalas en orden.

Actualizar, y retirar algo

El id es el nombre del archivo sin su extensión, y es lo que hace que una actualización sea una actualización. Mantén el nombre y una versión nueva reemplaza la copia que ya tiene la gente. Renombra el archivo y habrás publicado un segundo paquete junto al primero.

Quitar un paquete del repositorio detiene las descargas nuevas. No llega a los teléfonos que ya lo tienen, así que trata una mala versión como algo que reemplazar, no que borrar.

Repositorios oficiales

Haz un fork de cualquiera de estos para empezar. Cada uno genera su propio manifiesto y se publica con GitHub Actions.