Package-Format (.sellxpkg)

Eine .sellxpkg-Datei ist ein ZIP-Archiv mit einer definierten Struktur — manifest.json, sql/-Verzeichnis und optionale Metadaten-Files.

Entwickler-Handbuch · Plugin-Authoring

Datei-Endung

Endung: .sellxpkg (nicht .zip)
MIME-Type beim Upload: application/x-sellx-package
Max. Größe: 50 MB (Hard-Limit im Sidecar)

Verzeichnis-Layout

textlayout.txt

mein-plugin.sellxpkg/
├── manifest.json        ← Pflicht
├── sql/                 ← Pflicht
│   ├── q1.sql           ← Query-Datei (Name muss zu manifest.queries[].id passen)
│   ├── q2.sql
│   └── …
├── icon.png             ← Optional (256x256, quadratisch, max. 500 KB)
├── README.md            ← Optional (für Plugin-Store-Listing)
└── CHANGELOG.md         ← Optional

Wichtig: Alle Pfade in der ZIP sind case-sensitive (Linux-Sidecar-Verhalten).

Packen

Variante A: zip-CLI

bashpack-zip.sh

cd mein-plugin
zip -r ../mein-plugin.sellxpkg . -x "*.DS_Store" "*.swp"

Variante B: PowerShell

bashpack-powershell.sh

Compress-Archive -Path mein-plugin/* -DestinationPath mein-plugin.sellxpkg

Variante C: 7-Zip

bashpack-7zip.sh

7z a mein-plugin.sellxpkg mein-plugin/*

Hinweis: Die ZIP darf keine führende Verzeichnis-Ebene enthalten. manifest.json muss direkt im Root liegen, nicht unter mein-plugin/manifest.json.

Validierung

bashvalidate.sh

# Strukturcheck
unzip -l mein-plugin.sellxpkg
# Sollte enthalten:
#   manifest.json
#   sql/<id>.sql
#   …

# Manifest-Parsing testen
unzip -p mein-plugin.sellxpkg manifest.json | jq .

Pflicht-Inhalt

Datei	Pflicht	Beschreibung
`manifest.json`	Ja	Plugin-Metadaten + Query-Liste
`sql/<query-id>.sql`	Ja	Eine Datei pro Query-ID aus dem Manifest
`icon.png`	Nein	Plugin-Icon, fallback = default-icon
`README.md`	Nein	Markdown, im Plugin-Store angezeigt
`CHANGELOG.md`	Nein	Markdown, im Plugin-Store angezeigt

Versionsnummern

Die version im Manifest folgt semver:

textsemver.txt

MAJOR.MINOR.PATCH
  │     │     └── Bugfixes, keine API-Änderung
  │     └──────── Neue Features, abwärtskompatibel
  └────────────── Breaking Changes (Manifest-Schema-Änderung)

Der Hub lehnt ein Downgrade ab — Plugins können nur auf eine gleiche oder höhere Version aktualisiert werden.

Signatur (geplant)

In sellx Central wird das Plugin mit einem Ed25519-Schlüssel signiert. Der Hub verifiziert die Signatur beim Install. Lokal-unsignierte Plugins sind nur für Entwicklung/Testing erlaubt.