Plattform und CLI

Was Inhaber auf der Plattform tun

Die Plattform ist eine gehostete Web-App, betrieben von Lupinum und auf Einladung offen. Sie zeigt aus deinen Bausteinen Formulare und speichert die Inhalte. Die Seite holt die Inhalte als Bundle von dort. Ohne Plattform liest eine Seite alle Inhalte aus Dateien.

• Anmeldung. Personen melden sich mit einem Code an, der per E-Mail kommt. Ein Konto entsteht nur mit Einladung.
• Rollen. Ein Inhaber (owner) darf alles auf seiner Seite und lädt Mitarbeiter ein. Ein Mitarbeiter (staff) darf nur die Aufgaben, die der Inhaber ihm freigibt. Ein Admin darf alles auf allen Seiten.
• Bearbeiten. Inhaber ändern Einträge in Formularen. Aufgaben aus den Bausteinen sind Kurzwege für häufige Handgriffe. Eine Vorschau zeigt die echte Seite mit den geänderten Inhalten.
• Speichern und Veröffentlichen. Speichern bringt nichts online: Ein neuer Eintrag ist ein Entwurf, Änderungen an einem Eintrag oder Einzelstück, das online ist, warten als unveröffentlichte Änderungen. „Veröffentlichen …“ bringt sie jetzt oder zu einer Zeit online, „Verwerfen“ geht zur Fassung auf der Website zurück. Ein Eintrag einer Sammlung kann wieder zum Entwurf werden (offline, ohne ihn zu löschen); ein Einzelstück bleibt immer online. Eine Aufgabe auf „Heute“ veröffentlicht mit einem Druck auf „Veröffentlichen“. Verschieben im Navigationsbaum geht sofort online.
• Sicherheit. Ändern zwei Personen dasselbe Feld, merkt die Plattform den Konflikt. Eine Änderung lässt sich rückgängig machen. Gelöschte Einträge bleiben 30 Tage wiederherstellbar.
• Freigabe. Auf Wunsch braucht eine Aufgabe oder ein Agenten-Schlüssel ein Ja, bevor eine Änderung online geht. Wer freigibt, sieht die Änderung und gibt sie frei, gibt sie für eine Zeit frei oder lehnt sie mit einem Satz ab; die Person, die sie gemacht hat, sieht den Grund. Ohne Einstellung ist die Freigabe aus.
• Zeitplan. Ein Entwurf oder unveröffentlichte Änderungen gehen zu einem festen Zeitpunkt online. Ein Release veröffentlicht mehrere Änderungen zusammen.
• Verlauf. Der Verlauf zeigt jede Änderung, mit „Änderungen anzeigen“ und „Zurück zu dieser Version“.
• Übersetzungen. Ändert jemand einen Text in der Hauptsprache, gilt die Übersetzung als veraltet. Die Seite zeigt sie weiter, bis jemand sie bestätigt oder neu schreibt; das Studio listet sie.
• Sofort neu laden. Die Seite lädt Inhalte höchstens alle 60 Sekunden neu. Ein Inhaber kann eine Seite sofort neu laden lassen, zum Beispiel um einen Eintrag von der Seite zu nehmen. Dafür braucht die Seite ein Token (siehe Veröffentlichen).

Du als Entwickler legst die Bausteine fest. Die Inhaber füllen sie.

Das CLI

ginko ist ein Befehl im Paket @lupinum/ginko. Er hat drei Befehle: check, release und export. Die Befehle laden deine ginko.config.ts (Standard: ./ginko.config.ts). Mit --config <datei> nennst du eine andere Datei. Die Meldungen des CLI sind auf Englisch. In einem Projekt startest du es mit pnpm exec ginko <befehl> oder aus einem Skript in der package.json.

pnpm exec ginko check

npx ginko check

yarn ginko check

ginko --help listet die Befehle auf, ginko --version gibt die Version aus.

Das CLI lädt ginko.config.ts mit der Typ-Entfernung von Node, nicht mit dem Loader von Nuxt. Darum brauchen relative Importe in der Konfiguration die Endung .ts (import { menu } from './bricks/menu.ts'), und Aliase wie ~/ funktionieren nicht. nuxt build nimmt beides an. Eine Konfiguration, die auf Dateien verteilt ist, kann also bauen und trotzdem in ginko check scheitern.

Umgebungsvariablen

Das sind alle GINKO_*-Variablen, die das CLI liest. Das CLI liest keine .env-Dateien: Setze die Variablen in der Shell oder als CI-Secrets. (Die Nuxt-Seite liest .env. Ein Wert nur in .env erreicht also die Seite, aber nicht das CLI.)

Eine Seite mit nur Datei-Bausteinen braucht für ginko check keine davon. release und export brauchen immer GINKO_PLATFORM und GINKO_KEY. Zwei weitere GINKO_*-Namen gibt es, aber nicht für Seiten: GINKO_LOCAL gehört zur lokalen Plattform im Ginko-Monorepo, GINKO_REGISTRY_URL zum Build der Ginko-Komponenten-Registry (siehe Veröffentlichen).

Ausgabe und Exit-Codes

Jeder Lauf gibt genau eine JSON-Zeile auf stdout aus. Meldungen für Menschen gehen auf stderr. Nur --help und --version geben einfachen Text aus. --json ist erlaubt, damit der Aufruf zu ginko-i18n passt.

Bei Erfolg beginnt die Zeile mit "ok":true, danach folgen die Felder des Befehls:

Bei einem Fehler lautet die Zeile {"ok":false,"error":{"code":"…","message":"…"}}, und der Exit-Code sagt, was zu tun ist:

error.code ist USAGE, INVALID, UNAVAILABLE, UNEXPECTED (ein Fehler der CLI selbst, zum Beispiel ein Ordner, in den sie nicht schreiben darf) oder der Code aus der Antwort der Plattform, zum Beispiel SCHEMA_REJECTED, CHANGED_SINCE, UNAUTHORIZED oder FORBIDDEN. Entscheide nach dem Exit-Code und nutze error.code für Logs: Neue Codes können dazukommen.

ginko check

ginko check
ginko check --offline

ginko check schreibt nichts. Es prüft drei Dinge:

1. Deine ginko.config.ts, mit derselben Prüfung wie nuxt build. Ist die Konfiguration ungültig, listet es die Probleme auf und hört auf.
2. Die Inhaltsdateien in content/, ihre Links, und dass seo.image (ein Pfad) in public/ liegt.
3. Bei einer Seite mit Plattform-Bausteinen: dein Schema gegen production. Es zeigt die erlaubten Änderungen, neue Migrationen und die Größe der Inhalte. Es meldet jede Ablehnung mit einem Vorschlag, wie du sie löst. Dieser Schritt braucht GINKO_PLATFORM und GINKO_KEY.

Mit --offline führt es nur die Schritte 1 und 2 aus und gibt Skipped the comparison with production (--offline). aus. Nutze das, wo der Schlüssel fehlt, zum Beispiel bei einem Pull Request aus einem Fork: GitHub gibt ihm keine Secrets.

Eine Seite mit nur Datei-Bausteinen gibt OK: schema and links are fine. aus, wenn alle Prüfungen bestehen. Bei einem Problem endet ginko check mit Exit-Code 1. Nutze es in der CI bei jedem Pull Request.

Externe Links (http://… und https://…) fragt ginko check nur, wenn du linkCheck: { external: 'error' } (oder 'warn') setzt. Es fragt jede Adresse einmal an und meldet nur sichere Fälle: 404, 410, einen unbekannten Host oder zwei Zeitüberschreitungen. Antworten wie 403 oder 429 zählen nicht, weil viele Seiten Bots sperren. Gute Ergebnisse merkt sich Ginko sieben Tage in node_modules/.cache/ginko. Dieselbe Prüfung läuft bei nuxt build und nuxt generate, nie im Dev-Modus. Ohne die Option fragt Ginko kein Netzwerk an.

ginko release

ginko release

ginko release bringt Schema und Inhalte nach production. Du führst es in der CI auf main aus. Es braucht git und Zugriff auf das Remote. Es tut Folgendes:

1. Es prüft, ob der Release-Commit (GINKO_COMMIT oder GITHUB_SHA) noch der neueste Commit von main auf origin ist (GINKO_BRANCH und GINKO_REMOTE ändern beides). Sonst gibt es {"ok":true,"deploy":false,"reason":"superseded"} aus und endet mit Exit-Code 0.
2. Es lädt den Stand von production und prüft dein Schema (siehe unten).
3. Es führt Migrationen aus und prüft alle Einträge.
4. Es schreibt alles in einem Schritt. Hat sich production inzwischen geändert, versucht es bis zu fünf Mal erneut.

Bei Erfolg gibt es {"ok":true,"deploy":true,"schemaRev":…,"contentRev":…} aus. Dasselbe Release mit gleichem Commit zu wiederholen ist sicher.

Ein überholtes Release ist kein Fehler, darum endet es mit Exit-Code 0. Deploye die Seite nur, wenn deploy den Wert true hat:

# GitHub Actions führt das mit bash -e aus: Die Exit-Codes 1 bis 4 beenden den Job.
result=$(pnpm exec ginko release)
if [ "$(echo "$result" | jq -r .deploy)" = "true" ]; then
  pnpm exec vercel deploy --prod   # oder der Deploy-Befehl deines Hosts
fi

ginko export

ginko export ginko-export-meine-seite

ginko export [ordner] sichert Schema, alle Einträge (auch gelöschte) und alle Dateien von production in einen Ordner. Der Ordner muss neu oder leer sein. Ohne Ordner heißt er ginko-export-<seite>-<jjjj-mm-tt>. Er enthält export.json und den Ordner files/. export.json wird zuletzt geschrieben: Ein Ordner mit dieser Datei ist vollständig. Der Befehl gibt {"ok":true,"dir":…,"entries":…,"files":…} aus. Er braucht einen Schlüssel mit dem Bereich export oder pull. Führe ihn wöchentlich in der CI aus und lade den Ordner als Artefakt hoch. Ohne CLI laden Inhaber und Admins denselben Ordner als ZIP-Datei im Studio unter Team, „Sicherung herunterladen“; entpackt liest local:import ihn wie einen Export.

ginko prepare-import

Du ziehst eine Seite von einer alten Website zu Ginko um? Dann füllst du von Hand oder mit einem Skript einen Ordner im Export-Format: export.json mit Schema und Einträgen, dazu der Ordner files/. Das ist derselbe Aufbau wie bei ginko export. Bilder und Komponenten stehen dabei noch so da, wie die alte Seite sie kennt: als Adresse (https://…), mit alten Tag-Namen. ginko prepare-import macht daraus einen Ordner, den Lupinum unverändert mit ops:import laden kann.

ginko prepare-import umzug --map map.json --config ginko.config.ts

Die Map-Datei ist JSON. Alle Schlüssel sind optional:

{ "images": { "folder": "importiert" },
  "components": { "ginko-layout": "layout", "ginko-column": { "tag": "column", "attributes": { "size": "width" } } },
  "redirects": { "/alt/ueber-uns": "pages/ueber-uns", "/kontakt.html": "/kontakt" } }

• Bilder: Jede Adresse mit http oder https in einem Bildfeld ({ "url": … } oder ein Text) und in Markdown (![Alt](https://…)) wird geladen (20 Sekunden, höchstens 20 MB, nur JPEG, PNG und WebP, wie beim Hochladen im Studio). Jedes Bild liegt einmal in files/, auch wenn mehrere Adressen dieselben Bytes liefern. Im Text steht danach $file.<sha256>, im Bildfeld { "file": "<sha256>", "alt": … }. Die Bilder liegen im Ordner images.folder der Dateiablage (Standard imported). Eine Adresse, die nicht klappt, bleibt stehen. Der Befehl macht trotzdem alles andere fertig, listet sie auf und endet mit Exit-Code 1.
• Komponenten: components benennt Tags um (::alt, :::alt, :alt) und auf Wunsch Attribute in {…}. Tags, die defineComponents der Seite nicht kennt, stehen als Warnung in components.unknown. Das ist kein Fehler.
• Weiterleitungen: redirects ordnet jedem alten Pfad ein Ziel zu: <baustein>/<id> ist die Adresse des Eintrags laut route des Bausteins. Beginnt der alte Pfad mit einer Sprache (/en/…), gilt die Adresse dieser Sprache. Ein Ziel mit / wird übernommen. Das Ergebnis liegt in redirects.json im Ordner. Kopiere die Liste in redirects in ginko.config.ts. Ein unbekannter Eintrag steht in redirects.problems.

export.json wird an Ort und Stelle geändert. Vorher legt der Befehl export.json.bak an. Ein zweiter Lauf ändert nichts und lädt nichts noch einmal. Mit --config (oder einer ginko.config.ts im aktuellen Ordner) kennt der Befehl die Routen und Komponenten der Seite. Er gibt {"ok":…,"images":{"downloaded":…,"reused":…,"failed":[…]},"components":{"renamed":…,"unknown":[…]},"redirects":{"count":…,"file":…,"problems":[…]}} aus.

Danach schickst du den Ordner an Lupinum. Wir laden ihn mit ops:import in die Seite.

Eine Plattform-Seite entwickeln

Außerhalb des Ginko-Monorepos gibt es keine lokale Plattform. Lass deine Seite stattdessen gegen die gehostete Plattform laufen. Schreib ihre Adresse in die ginko.config.ts; dann läuft npm run dev ohne .env-Datei, in jedem Klon und jedem Worktree:

export default defineSite({
  site: 'linde',
  url: 'https://linde.example',
  platform: 'https://platform.example.com',
  // …
})

NUXT_PUBLIC_GINKO_PLATFORM überschreibt platform, etwa für einen Lauf gegen eine andere Plattform. pnpm local:dev im Monorepo setzt die Variable auf die lokale Plattform; ein lokaler Test liest also nie die gehosteten Inhalte. Ohne platform und ohne Variable liest dev die lokale Plattform auf http://localhost:3100.

Die Seite zeigt die veröffentlichten Inhalte. Deine lokale ginko.config.ts bestimmt, was die Seiten bekommen:

• Ein neuer Baustein ist leer.
• Ein neues Feld mit default hat seinen Standardwert.
• Ein neues optionales Feld hat keinen Wert.

Inhaber können neue Felder erst nach ginko release füllen. Mit ginko check siehst du, ob production deine Schema-Änderungen annimmt.

Werkzeuge des Ginko-Monorepos

Das Ginko-Repository hat vier weitere Befehle. Sie brauchen die lokale Plattform (apps/platform und ihr Backend in packages/ginko-server), darum gehören sie nicht zum veröffentlichten Befehl ginko. Starte sie im Hauptordner des Repositorys. local:dev braucht die Konfiguration der Seite mit --config:

pnpm local:dev --config sites/restaurant/ginko.config.ts
pnpm local:pull
pnpm local:import ginko-export-meine-seite

Sie geben eine JSON-Zeile aus und nutzen die Exit-Codes von ginko.

local:dev startet alles lokal: ein lokales Convex-Backend, die Plattform und deine Seite mit nuxt dev. Es schickt dein Schema an die lokale Plattform, sofort und nach jeder Änderung der ginko.config.ts. Abgelehnte Änderungen erscheinen als Warnung, laufen aber durch. So darfst du lokal frei probieren. Ändert sich eine Datei, die die Konfiguration importiert, musst du local:dev neu starten. Ctrl-C beendet alle Prozesse. Für eine Seite mit nur Datei-Bausteinen reicht nuxt dev.

Sobald du dich einmal in der lokalen Plattform angemeldet hast, schreibt local:dev die Datei .mcp.json in den Ordner der Seite (Server ginko-local). Ein Agent wie Claude Code, der in diesem Ordner läuft, arbeitet damit als Admin im lokalen CMS: Er liest das Schema, schreibt Inhalte, importiert und lädt Dateien hoch. Andere Server in der Datei bleiben, der Schlüssel bleibt bei jedem Start derselbe und gilt nur lokal. Nimm .mcp.json in die .gitignore auf.

local:pull kopiert die Inhalte von production in die lokale Plattform. Es führt export aus, dann import. So testest du mit echten Inhalten. Der Befehl braucht GINKO_PLATFORM und GINKO_KEY mit dem Bereich pull oder export. Er ersetzt die Inhalte der Seite lokal.

local:import <ordner> lädt einen Export in die lokale Plattform. Es ersetzt dort die Einträge der Seite. Personen bleiben erhalten. Damit prüfst du, ob ein Backup sich wiederherstellen lässt.

local:files-export --config <Datei> [Ordner] macht aus den Markdown- und YAML-Dateien einer Seite einen Export-Ordner (Standard ginko-export-<site>-files). Es liest für jeden Baustein content/<Baustein>/ neben der Konfiguration, egal welche source er hat, mit demselben Leser wie der Build der Seite, und behält Übersetzungen (*.en.md). Danach lädt local:import <Ordner> den Ordner, und das Studio zeigt die Datei-Inhalte. So siehst du die Dateien einer Seite in der Plattform, bevor du ihre Bausteine dorthin verlegst. Bilder bleiben einfache Pfade; es werden keine Dateien hochgeladen.

pnpm ops:import <Ordner> --site <slug> --prod ist für Lupinum-Betreiber. Es lädt einen Export-Ordner in eine leere Seite der gehosteten Plattform und braucht --prod und Convex-Zugriff auf Produktion. Führe vorher ginko release für die Seite aus: Der Befehl pusht kein Schema und bricht ab, wenn dem veröffentlichten Schema ein Baustein des Exports fehlt. Eine Seite, die schon Einträge, Änderungen oder Bearbeitungen hat, lehnt er ab, und er löscht nie Inhalte.

local:pull und local:import laufen nur gegen die lokale Plattform und brechen ab, bevor sie etwas schreiben, wenn das Ziel nicht lokal ist.

Schemas wachsen nur

Ein Schema in production darf nur wachsen. Inhalte gehören Menschen, und ältere Versionen deiner Seite lesen noch das alte Schema. Darum lehnt ginko check und ginko release Änderungen ab, die Daten oder alten Code brechen könnten. Die Regel: Alles, was nicht ausdrücklich erlaubt ist, wird abgelehnt.

Erlaubt:

• neue Bausteine; in einem neuen Single braucht jedes Pflichtfeld einen default. f.markdown, f.image und f.file können keinen haben, darum setzt du bei ihnen optional: true
• neue freiwillige Felder
• neue Pflichtfelder mit default oder mit einer Migration, die sie füllt
• neue Optionen in choice und choices
• höheres max und kleineres min
• neue Texte: label, hint, describe, itemLabel, Option-Labels
• neue Sprachen am Ende von locales
• Änderungen an pages, tasks, order, visible und untranslated
• Änderungen an components: die Veröffentlichung prüft jeden gespeicherten Text neu, eine Komponente, Eigenschaft oder Option, die ein Text noch nutzt, kann also nicht wegfallen

Abgelehnt:

• ein Feld oder Baustein, der fehlt (nicht umbenennen, nicht löschen)
• ein anderer Typ
• ein freiwilliges Feld, das Pflicht wird
• eine entfernte Option
• kleineres max, größeres min
• geänderte Übersetzbarkeit, step, currency, route, timeZone oder Hauptsprache
• eine entfernte Sprache
• ein geänderter default

Es gibt also kein Umbenennen und keinen Typwechsel. Willst du ein Feld ersetzen, legst du ein neues an, füllst es mit einer Migration und ziehst das alte zurück. Für jede abgelehnte Änderung zeigt ginko check genau diese Zeilen der Konfiguration, mit deinen Namen von Baustein und Feld: übernimm sie, setze die ID der Migration (YYYY-MM) und wandle den Wert um, wo sich der Typ ändert.

export default defineSite({
  // …
  bricks: {
    menu: collection({
      label: 'Speisekarte',
      fields: {
        headline: f.text('Überschrift'),   // bleibt unverändert in fields
        title: f.text('Titel'),            // neues Pflichtfeld
      },
      max: 150,
      order: 'manual',
    }),
  },
  // Das alte Feld zeigt im Bundle weiter den aktuellen Wert von title.
  retired: { 'menu.headline': { from: 'title' } },
  migrations: {
    '2026-11-title-from-headline': {
      brick: 'menu',
      fills: 'title',
      compute: (entry) => entry.headline,
    },
  },
})

• retired zieht ein Feld zurück. Im Editor verschwindet es. Im Bundle bleibt es erhalten, damit ältere Versionen der Seite weiterlaufen. from spiegelt den Wert eines anderen Feldes; das geht nur, wenn jeder Wert dieses Feldes in die alte Definition passt (gleicher Typ, gleiche Übersetzbarkeit, gleiches Format und gleiche Währung, Grenzen und Optionen innerhalb der alten). Mit value legst du einen festen Wert fest. Ein freiwilliges Feld kann auch ohne Wert gehen: { drop: true }. Einen ganzen Baustein ziehst du mit retired: { gallery: { drop: true } } zurück.
• Eine Migration ist eine reine Funktion. Sie hat keinen Zugriff auf Netzwerk, Uhr oder Zufall. Sie läuft in ginko release auf deinem Rechner oder in der CI, nie auf der Plattform. Ihre ID sieht aus wie 2026-11-name. Eine bekannte Migration darfst du nicht mehr ändern.

Bausteine mit source: 'files' gehören nicht zum Schema der Plattform. Für sie gilt diese Regel nicht.

Intern, nicht verwenden

Ginko nutzt diese Namen im Modul. Sie gehören nicht zur API und können sich in jeder Version ändern, auch in einem Patch. Lies Inhalte und Daten der Seite stattdessen mit den Composables und Komponenten aus Seiten lesen.

• useState-Schlüssel, die mit ginko: beginnen, etwa ginko:bundle, ginko:today und ginko:preview.
• Die provide-Schlüssel ginko:components und ginko:toc.
• Die virtuellen Module #ginko/*, etwa #ginko/schema und #ginko/files.
• Die { ref }-Form eines Markdown-Werts. Ginko hält lange Texte aus dem Payload der Seite heraus, bei Datei- und Plattform-Bausteinen, und <GinkoMarkdown> lädt sie nach. Gib den Wert so weiter, wie er ist; lies oder baue nie ein { ref }. Die Zahl der Wörter gibt dir wordsOf(value).
• Die Komponente GinkoCard, die Vorlage der erzeugten Teilen-Karte. Stell die Karte über useGinkoSeo ein.
• Die Werte in runtimeConfig.public.ginko und runtimeConfig.ginkoRevalidateToken. Lies Daten der Seite mit useGinkoSite(), und setz nur die Umgebungsvariablen aus Veröffentlichen.
• Die Header x-ginko-rev, x-ginko-min-rev und x-ginko-site-token und die Nachrichten zwischen Vorschau und Plattform (ginko:preview, ginko:ready, ginko:navigate).
• Adressen unter /__ginko/ außer den stabilen aus Adressen und Header.
• Der Nuxt-Hook ginko:files. @lupinum/ginko-docs nutzt ihn, um für seine Bearbeiten-Links die Quelldatei jedes Eintrags zu behalten.