Plugins officiels

Les plugins officiels sont maintenus aux côtés de pubm et suivent les mêmes attentes de release et de compatibilité que le projet central. Utilisez-les quand vous voulez une intégration solide et bien prise en charge sans repartir de zéro.

@pubm/plugin-brew

@pubm/plugin-brew aide les projets CLI à maintenir les formules Homebrew synchronisées avec chaque release. Si le pipeline échoue après l’ouverture de la PR, il enregistre des actions de rollback pour fermer cette PR Homebrew.

Quand l’utiliser

• distribuer un binaire CLI via Homebrew
• mettre à jour automatiquement un dépôt tap dédié
• garder les checksums des formules alignés avec les artefacts de release

Configuration courante

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",
    }),
  ],
});

Options

Option	Type	Description
formula	string	Chemin de la formula relatif à la racine du dépôt.
repo	string	URL facultative du dépôt tap distant. Si elle est omise, le dépôt courant est utilisé.
packageName	string	Filtre de nom de package facultatif. Quand il est défini, le plugin ne s’exécute que pour les releases correspondant à ce nom de package. Utile dans les monorepos.
assetPlatforms	Record<string, (asset: ReleaseAsset) => boolean>	Matchers de plateforme personnalisés facultatifs. Remplace la logique de correspondance par défaut os + arch.

Correspondance des plateformes

Le plugin utilise les données structurées ParsedPlatform de chaque ReleaseAsset pour associer les artefacts aux entrées de plateforme de la formula. La logique de correspondance par défaut couvre quatre plateformes :

Clé de formula	Correspond quand
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"

Cela remplace l’ancienne approche consistant à faire du matching sur des chaînes dans le nom des artefacts, par exemple asset.name.includes("darwin-arm64"), qui était fragile quand les noms changeaient.

Matchers de plateforme personnalisés

Utilisez assetPlatforms lorsque la correspondance par défaut os + arch ne suffit pas, par exemple si vous voulez uniquement les builds musl pour Linux :

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

Chaque prédicat reçoit un ReleaseAsset et renvoie true si l’artefact doit être utilisé pour cette entrée de formula.

Credentials et checks de preflight

@pubm/plugin-brew déclare automatiquement ses credentials et ses checks. Vous n’avez pas besoin de les configurer manuellement.

Credential requis :

Variable d’environnement	Nom du GitHub Secret	Rôle
PUBM_BREW_GITHUB_TOKEN	PUBM_BREW_GITHUB_TOKEN	GitHub Personal Access Token avec la portée repo, utilisé pour pousser les mises à jour de formula et ouvrir des pull requests.

En local, pubm demande ce token et le stocke dans le keyring du système. En CI, passez-le via la variable d’environnement PUBM_BREW_GITHUB_TOKEN. Exécutez pubm --mode ci --phase prepare ou pubm secrets sync pour synchroniser le token stocké vers les GitHub Secrets du dépôt et le rendre disponible aux workflows CI.

Le plugin enregistre aussi un check de preflight qui vérifie que le token est présent et qu’il dispose de l’accès dépôt nécessaire avant le début de la phase de publish.

Comportement

Le plugin peut :

• créer un squelette de formula lorsqu’il n’en existe pas
• mettre à jour les valeurs url et sha256 des artefacts de release en utilisant les informations de plateforme structurées
• commit et pousser les changements de formula
• retomber sur un workflow de pull request lorsque le push direct n’est pas approprié

Commande associée

pubm brew init

Utilisez-la pour générer une formula de départ à partir des métadonnées du package.

brewCore

Pour contribuer à homebrew/homebrew-core (le dépôt Homebrew par défaut), utilisez brewCore au lieu de brewTap :

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

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

Option	Type	Description
formula	string	Chemin de la formula relatif à la racine du dépôt.
packageName	string	Filtre de nom de package facultatif pour les monorepos.
assetPlatforms	Record<string, (asset: ReleaseAsset) => boolean>	Matchers de plateforme personnalisés facultatifs.

brewCore fork homebrew/homebrew-core, met à jour la formula et ouvre automatiquement une PR. Comme brewTap, il déclare aussi automatiquement le credential PUBM_BREW_GITHUB_TOKEN et un check de preflight.

@pubm/plugin-external-version-sync

Ce plugin garde les fichiers hors manifest alignés sur la version de votre package. Enregistre des actions de rollback pour restaurer le contenu original des fichiers si le pipeline échoue après la synchronisation de version.

Utilisez-le lorsqu’une release doit aussi mettre à jour :

• les extraits d’installation dans README.md
• les exemples de documentation
• les manifests d’application
• les constantes source
• les fichiers JSON de métadonnées

Configuration typique

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.-]+)/,
        },
      ],
    }),
  ],
});

Types de cibles

regex

À utiliser pour les fichiers texte arbitraires :

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

Exigences :

• le motif doit isoler la version dans exactement un groupe de capture
• le fichier doit avoir un format stable pour que l’automatisation de release puisse le mettre à jour sans risque

json

À utiliser pour les manifests lisibles par machine :

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

Quand utiliser pubm sync --discover

Si vous ne savez pas où les versions apparaissent dans votre dépôt, exécutez :

pubm sync --discover

Cette commande analyse les références de version probables et affiche les fichiers et chemins candidats que vous pouvez adapter dans la config du plugin.

Choisir entre plugins officiels et plugins personnalisés

Utilisez un plugin officiel lorsque :

• votre besoin correspond à une intégration existante
• vous voulez une configuration moins coûteuse à maintenir
• le chemin de release est assez courant pour bénéficier d’une standardisation

Construisez un plugin personnalisé lorsque :

• votre registry ou votre workflow post-release est spécifique à l’organisation
• vous avez besoin d’une politique ou d’une logique de déploiement personnalisée
• vous voulez des commandes CLI supplémentaires pour les opérateurs

Lisez la Référence de l’API des plugins si vous devez aller au-delà de l’ensemble officiel.

Automatisation de configuration pour agents de code

Les plugins runtime ne sont qu’une partie de l’histoire. Ce dépôt fournit aussi un bundle pubm plugin sous plugins/pubm-plugin/skills/* pour les workflows d’agents de code tels que :

• la configuration de la release
• l’aide à la publication en mode aperçu d’abord
• la découverte de synchronisation de version
• le scaffolding de plugins

Si vous intégrez pubm dans un environnement d’agent, associez les plugins runtime à ces assets de type skill pour que les flux de configuration et de publication restent explicites et reproductibles.

Lisez le guide Intégration des agents de code pour le schéma d’intégration.