Offizielle Plugins

Offizielle Plugins werden gemeinsam mit pubm gepflegt und folgen denselben Release- und Kompatibilitaetserwartungen wie das Kernprojekt. Verwende sie, wenn du eine stabile, gut unterstuetzte Integration willst, ohne das Plugin selbst von Grund auf zu bauen.

@pubm/plugin-brew

@pubm/plugin-brew hilft CLI-Projekten dabei, Homebrew-Formulae mit jedem Release synchron zu halten. Falls die Pipeline nach dem Erstellen der PR fehlschlaegt, registriert es Rollback-Aktionen, um die Homebrew-PR wieder zu schliessen.

Wann es passt

• ein CLI-Binary über Homebrew ausliefern
• ein dediziertes Tap-Repository automatisch aktualisieren
• Formula-Prüfsummen mit den Release-Artefakten synchron halten

Typische Config

import { defineConfig } from "@pubm/core";
import { brewTap } from "@pubm/plugin-brew";

export default defineConfig({
  plugins: [
    brewTap({
      formula: "Formula/my-tool.rb",
      repo: "https://github.com/my-org/homebrew-tap",
    }),
  ],
});

Optionen

Option	Typ	Beschreibung
formula	string	Pfad der Formula relativ zum Repository-Root.
repo	string	Optionaler URL des entfernten Tap-Repositories. Wenn weggelassen, wird das aktuelle Repository verwendet.
packageName	string	Optionaler Filter für den Paketnamen. Wenn gesetzt, laeuft das Plugin nur für Releases, die zu diesem Paketnamen passen. Praktisch in Monorepos.
assetPlatforms	Record<string, (asset: ReleaseAsset) => boolean>	Optionale benutzerdefinierte Plattform-Matcher. Überschreibt die Standardlogik für os + arch.

Plattform-Matching

Das Plugin verwendet strukturierte ParsedPlatform-Daten aus jedem ReleaseAsset, um Artefakte den Formula-Plattform-Eintraegen zuzuordnen. Die Standardlogik deckt vier Plattformen ab:

Formula-Schlüssel	Passt, wenn
darwin-arm64	asset.platform.os === "darwin" && asset.platform.arch === "arm64"
darwin-x64	asset.platform.os === "darwin" && asset.platform.arch === "x64"
linux-arm64	asset.platform.os === "linux" && asset.platform.arch === "arm64"
linux-x64	asset.platform.os === "linux" && asset.platform.arch === "x64"

Das ersetzt den bisherigen Ansatz, Asset-Namen per String-Matching zu prüfen, zum Beispiel asset.name.includes("darwin-arm64"), der bei Namensänderungen fragil war.

Benutzerdefinierte Plattform-Matcher

Verwende assetPlatforms, wenn das Standard-Matching über os + arch nicht ausreicht, zum Beispiel wenn du für Linux nur musl-Builds haben willst:

brewTap({
  formula: "Formula/mytool.rb",
  assetPlatforms: {
    "darwin-arm64": (asset) =>
      asset.platform.os === "darwin" && asset.platform.arch === "arm64",
    "linux-x64": (asset) =>
      asset.platform.os === "linux" &&
      asset.platform.arch === "x64" &&
      asset.platform.abi === "musl",
  },
})

Jedes Prädikat erhält ein ReleaseAsset und gibt true zurück, wenn das Artefakt für diesen Formula-Eintrag verwendet werden soll.

Credentials und Preflight-Checks

@pubm/plugin-brew deklariert die benötigten Credentials und Checks automatisch. Du musst sie nicht manuell konfigurieren.

Erforderliches Credential:

Umgebungsvariable	GitHub-Secret-Name	Zweck
PUBM_BREW_GITHUB_TOKEN	PUBM_BREW_GITHUB_TOKEN	GitHub Personal Access Token mit repo-Scope, um Formula-Updates zu pushen und Pull Requests zu öffnen.

Bei lokalen Läufen fragt pubm nach diesem Token und speichert es im System-Keyring. In CI stellst du das Token über die Umgebungsvariable PUBM_BREW_GITHUB_TOKEN bereit. Fuehre pubm --mode ci --phase prepare oder pubm secrets sync aus, um das gespeicherte Token in die GitHub Secrets deines Repositories zu synchronisieren, damit CI-Workflows es direkt nutzen können.

Das Plugin registriert außerdem einen Preflight-Check, der vor Beginn der Publish-Phase prüft, ob das Token vorhanden ist und den nötigen Repository-Zugriff hat.

Verhalten

Das Plugin kann:

• eine Formula-Vorlage erzeugen, wenn noch keine existiert
• url- und sha256-Werte für Release-Artefakte anhand strukturierter Plattforminformationen aktualisieren
• Formula-Änderungen committen und pushen
• auf einen Pull-Request-Workflow zurückfallen, wenn direkter Push nicht passt

Zugehöriger Befehl

pubm brew init

Nutze das, um aus Paketmetadaten eine startfähige Formula-Vorlage zu erzeugen.

brewCore

Für Beitrage zu homebrew-core (dem Standard-Homebrew-Repository) verwende brewCore statt brewTap:

import { brewCore } from "@pubm/plugin-brew";

export default defineConfig({
  plugins: [
    brewCore({
      formula: "Formula/my-tool.rb",
    }),
  ],
});

Option	Typ	Beschreibung
formula	string	Formula-Pfad relativ zum Repository-Root.
packageName	string	Optionaler Filter für den Paketnamen in Monorepos.
assetPlatforms	Record<string, (asset: ReleaseAsset) => boolean>	Optionale benutzerdefinierte Plattform-Matcher.

brewCore forkt homebrew/homebrew-core, aktualisiert die Formula und öffnet automatisch einen PR. Wie brewTap deklariert es außerdem automatisch das Credential PUBM_BREW_GITHUB_TOKEN und einen passenden Preflight-Check.

@pubm/plugin-external-version-sync

Dieses Plugin haelt Dateien außerhalb von Manifests mit deiner Paketversion synchron. Registriert Rollback-Aktionen, um den ursprünglichen Dateiinhalt wiederherzustellen, falls die Pipeline nach der Versionssynchronisierung fehlschlaegt.

Verwende es, wenn ein Release auch Folgendes aktualisieren soll:

• Installations-Snippets in README.md
• Beispiele in der Doku
• App-Manifests
• Source-Konstanten
• Metadaten-JSON-Dateien

Typische Config

import { defineConfig } from "@pubm/core";
import { externalVersionSync } from "@pubm/plugin-external-version-sync";

export default defineConfig({
  plugins: [
    externalVersionSync({
      targets: [
        {
          file: "src/constants.ts",
          pattern: /export const VERSION = "([^"]+)";/,
        },
        {
          file: "manifest.json",
          jsonPath: "metadata.version",
        },
        {
          file: "README.md",
          pattern: /pubm@([\\w.-]+)/,
        },
      ],
    }),
  ],
});

Zieltypen

regex

Verwende das für beliebige Textdateien:

{
  file: "README.md",
  pattern: /pubm@([\\w.-]+)/,
}

Voraussetzungen:

• das Muster muss die Version in genau einer Capture-Group isolieren
• die Datei sollte ein stabiles Format haben, damit die Release-Automatisierung sie sicher aktualisieren kann

json

Verwende das für maschinenlesbare Manifests:

{
  file: "manifest.json",
  jsonPath: "metadata.version",
}

Wann du pubm sync --discover verwenden solltest

Wenn du nicht sicher bist, wo Versionen in deinem Repository vorkommen, fuehre aus:

pubm sync --discover

Der Befehl durchsucht mögliche Versionsverweise und gibt Kandidaten-Dateien sowie Pfade aus, die du in die Plugin-Config uebernehmen kannst.

Wann du offizielle statt benutzerdefinierter Plugins waehlen solltest

Verwende ein offizielles Plugin, wenn:

• dein Bedarf zu einer bestehenden Integration passt
• du ein wartungsarmeres Setup willst
• der Release-Pfad allgemein genug ist, um von Standardisierung zu profitieren

Bau ein benutzerdefiniertes Plugin, wenn:

• deine Registry oder dein Post-Release-Workflow organisationsspezifisch ist
• du eigene Policy- oder Deployment-Logik brauchst
• du zusätzliche CLI-Befehle für Operatoren willst

Lies die Plugins API Reference, wenn du über den offiziellen Satz hinaus erweitern willst.

Automatisierung für Coding-Agent-Setups

Runtime-Plugins sind nur ein Teil der Geschichte. Dieses Repository liefert außerdem ein pubm plugin-Bundle unter plugins/pubm-plugin/skills/* für Coding-Agent-Workflows wie:

• Release-Setup
• Preview-first-Publish-Unterstützung
• Version-Sync-Discovery
• Plugin-Scaffolding

Wenn du pubm in eine Agenten-Umgebung integrierst, kombiniere Runtime-Plugins mit diesen skill-artigen Assets, damit Setup- und Publish-Flows explizit und wiederholbar bleiben.

Lies den Leitfaden Coding Agent Integration für das Integrations-Layout.