저장소

저장소란

Clink는 공개 GitHub 저장소에서 팩을 읽습니다. 이름으로 저장소를 추가하면 Clink가 최신 릴리스를 읽고, 모든 파일은 설치 전에 검증됩니다. 올라가는 것은 없고, 당신 것이 서버에서 실행되지도 않습니다.

owner/repository, github.com/owner/repository 또는 전체 HTTPS URL을 입력하세요. Clink는 무엇이든 다운로드하기 전에 모든 릴리스 매니페스트와 파일을 검증합니다.

종류를 고르세요

팩 종류마다 파일 확장자도, 매니페스트 안의 컬렉션 이름도 다르고, Clink는 각각에 서로 다른 크기 상한을 적용합니다. 배포할 행을 골랐으면 그 행을 그대로 따르세요. 패널 밑에 넣어 둔 테마는 아예 읽히지 않습니다.

언어 팩은 예외입니다. 그쪽의 팩은 문서 하나가 아니라 사전과 모델 파일 묶음이고, 공식 저장소가 그것을 만드는 도구 일습을 함께 담고 있습니다. 이 페이지 대신 그쪽 README부터 보세요.

공식 저장소에서 시작하기

가장 빠른 길은 포크입니다. 팩 폴더와 매니페스트 생성기, 릴리스 워크플로가 이미 연결된 채로 들어오고, 그대로 베낄 수 있는 예제까지 딸려 옵니다.

# 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

tools/와 .github/workflows/는 남겨 두세요. 푸시를 Clink가 읽을 수 있는 릴리스로 바꾸는 것이 이 둘이고, 이것 없는 포크는 아무것도 배포하지 못합니다.

또는 파일 세 개로 만들기

저장소에 특별한 것은 없습니다. 팩을 담을 폴더, 매니페스트를 쓰는 스크립트, 릴리스를 내는 워크플로면 됩니다.

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

워크플로가 하는 일은 세 가지입니다. 매니페스트를 다시 만들고, 이전 릴리스를 지우고, latest 태그로 새 릴리스를 올리면서 팩 파일과 매니페스트를 첨부합니다. 그게 전부입니다.

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

생성기는 폴더를 훑으며 파일마다 항목 하나씩을 씁니다. 해시와 바이트 수가 나오는 곳은 여기뿐이고, 그래서 손으로가 아니라 워크플로 안에서 돌립니다.

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

매니페스트

릴리스마다 팩 파일 옆에 manifest.json이 함께 올라가고, Clink는 최신 릴리스의 https://github.com/<owner>/<repository>/releases/latest/download/manifest.json에서 그것을 읽습니다. 각 항목에는 파일 이름, 같은 릴리스 안에서의 주소, SHA-256 해시, 정확한 바이트 수가 담깁니다.

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

컬렉션 이름은 종류와 맞아야 합니다. 패널은 panels, 테마는 themes, 위 표를 따라 그대로 이어집니다.

배포 전에 써 보기

저장소의 팩은 손으로 열 수 있는 바로 그 파일입니다. 그러니 지름길부터 쓰세요. 에어드롭으로 폰에 보내거나 파일 앱에 두고 Clink로 엽니다. 그런 다음 스크립트가 쓴 매니페스트를 확인합니다.

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

1. 생성기를 돌립니다. 그 순간 폴더에 있는 것을 기준으로 manifest.json을 다시 씁니다.
2. 쓰인 내용을 읽어 보세요. 모든 항목이 실제로 있는 파일을, 맞는 바이트 수와 함께 가리켜야 합니다.
3. 팩 파일 자체를 Clink에서 열어 써 봅니다. 패널이나 동작은 각자의 편집기로 들어가고, 거기서 실행할 수 있습니다.

배포

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

main에 푸시하면 나머지는 워크플로가 맡습니다. latest 릴리스에 더하는 것이 아니라 갈아 끼우므로, 가장 최근 푸시가 늘 다른 사람이 받는 것입니다.

저장소가 릴리스를 게시한 후에 이 탭을 여세요.

Clink에 추가하기

1. 일반을 열고 저장소로 들어가, owner/repository를 추가합니다.
2. 해당 종류의 탭을 열고 당겨서 새로 고칩니다. 매니페스트가 준 이름 그대로 팩이 나열됩니다.
3. 하나를 눌러 내려받습니다. Clink가 확인한 뒤 다른 팩과 똑같이 설치합니다.

데이터 팩(테마, 배열, 프로필, 사운드, 글꼴, 언어)은 저장소를 추가하는 것으로 충분합니다. 패널, 액션, 플러그인은 로직을 담고 있으므로, Clink가 이들을 설치하기 전에 저장소마다 별도의 스위치가 필요하며, 앱이 처음에 물어봅니다.

패널에는 제한된 인터랙티브 로직이 포함됩니다. 신뢰하는 저장소만 허용하세요.

Clink가 확인하는 것

1. 주소가 github.com의 HTTPS이고, 추가한 저장소의 릴리스 아래에 있는지.
2. 내려받은 크기가 매니페스트의 바이트 수와 정확히 같고, 64자 SHA-256 해시가 맞는지.
3. 파일이 올바른 확장자를 달고 있고, 스스로 밝힌 팩 종류로 해석되는지.
4. 패널, 액션, 플러그인은 저장되기 전에 소스 정책을 통과합니다.

다운로드가 거부된다면 이 다섯 가지 중 하나입니다. 앱의 메시지는 일부러 짧게 두었으니 순서대로 짚어 보세요.

업데이트, 그리고 거두어들이기

id는 확장자를 뺀 파일 이름이고, 업데이트를 업데이트로 만드는 것이 바로 이것입니다. 이름을 그대로 두면 새 릴리스가 사람들이 이미 가진 사본을 대신합니다. 이름을 바꾸면 첫 번째 옆에 두 번째 팩을 배포한 셈이 됩니다.

저장소에서 팩을 빼면 새 다운로드만 멈춥니다. 이미 받아 둔 폰에는 닿지 않으니, 잘못 나간 릴리스는 지우기보다 갈아 끼우는 쪽으로 다루세요.

공식 저장소

아무거나 하나 포크하면 시작할 수 있습니다. 각 저장소는 자기 매니페스트를 만들고 GitHub Actions로 스스로를 배포합니다.