Référence du SDK principal

@pubm/core est l’API programmatique derrière la CLI pubm. Cette page couvre les identifiants publics exportés depuis la racine du package :

import { ... } from "@pubm/core";

Le package fournit les déclarations de types ainsi que les points d’entrée ESM/CJS. Les métadonnées actuelles du package déclarent node >= 24.

Installation

npm install @pubm/core
pnpm add @pubm/core
bun add @pubm/core

Pipeline de release

pubm(options)

Exécute le même pipeline de release que celui qui alimente la CLI.

import { pubm } from "@pubm/core";

await pubm({
  version: "patch",
  dryRun: true,
  tag: "next",
});

pubm() accepte un objet Options. Les champs les plus importants sont :

Champ	Type	Rôle
version	string	Cible de release requise, comme patch, minor, major ou une version semver explicite.
dryRun	boolean	Afficher le plan des tâches sans modifier l’état Git ni publier.
mode	"local" | "ci"	Mode d’exécution : local (interactif) ou ci (non interactif, basé sur les tags).
prepare	boolean	Exécuter uniquement la phase de préparation (validation et vérifications dry-run de publication).
publish	boolean	Exécuter uniquement la phase de publication (publication depuis le dernier tag).
releaseDraft	boolean	Créer un draft GitHub Release au lieu d’une release publiée.
branch	string	Exiger une branche précise avant de publier.
anyBranch	boolean	Désactiver l’exigence de branche pour une exécution.
tag	string	Publier sous un dist-tag comme latest, next ou beta.
packages	PackageConfig[]	Remplacer les packages découverts automatiquement.

Pour les releases pilotées par la configuration, pubm() charge automatiquement pubm.config.*, résout la découverte des packages et branche les plugins avant d’exécuter le graphe de tâches.

Aides de configuration

Ces aides sont les principaux points d’entrée pour le code qui veut lire ou valider pubm.config.*.

Export	Nature	Rôle
defineConfig	function	Aide typée pour écrire pubm.config.ts.
loadConfig	function	Charger pubm.config.* depuis le disque et renvoyer PubmConfig | null.
resolveConfig	function	Appliquer les défauts, découvrir automatiquement les packages et normaliser les registries privés.
PubmConfig	type	Forme de configuration écrite par l’utilisateur.
ResolvedPubmConfig	type	Configuration entièrement résolue renvoyée par resolveConfig().
PackageConfig	type	Entrée de config par package utilisée par la découverte et la planification de publication.

import { defineConfig, loadConfig, resolveConfig } from "@pubm/core";

export default defineConfig({
  packages: [{ path: "packages/core" }],
});

const config = await loadConfig(process.cwd());
const resolved = config ? await resolveConfig(config, process.cwd()) : null;

PackageConfig sert à surcharger les registries, l’écosystème, la commande de build ou la commande de test par package :

type PackageConfig = {
  path: string;
  registries?: Array<"npm" | "jsr" | "crates" | string | PrivateRegistryConfig>;
  ecosystem?: "js" | "rust";
  buildCommand?: string;
  testCommand?: string;
};

API des plugins

Utilisez les exports de plugins lorsque vous voulez étendre le pipeline de publication avec des registries personnalisés, des écosystèmes, des hooks de cycle de vie ou des commandes CLI.

Export	Nature	Rôle
PubmPlugin	type	Contrat principal d’un plugin.
PluginHooks	type	Hooks de cycle de vie comme beforeBuild, afterPublish, onError, afterRelease et les hooks du pipeline d’artefacts.
HookFn / ErrorHookFn / AfterReleaseHookFn	type	Signatures de hooks.
PluginCommand / PluginSubcommand / PluginCommandOption	type	Modèle de commande CLI personnalisée pour les plugins.
PluginRunner	class	Utilitaire qui exécute les hooks et collecte les registries/écosystèmes des plugins chargés. Il expose aussi collectCredentials() et collectChecks() pour rassembler les descripteurs de credentials et les checks de preflight de tous les plugins enregistrés.
PluginCredential	type	Descripteur déclaratif d’un token ou secret requis par un plugin. Voir la Référence de l’API des plugins.
PluginCheck	type	Descripteur d’un check de preflight apporté par un plugin. Voir la Référence de l’API des plugins.
PluginTaskContext	type	Wrapper agnostique à listr2 passé à PluginCheck.task. Expose output, title et prompt().
GhSecretEntry	type	Une entrée renvoyée par les helpers de synchro GitHub Secrets : { secretName: string; token: string }.
collectPluginCredentials	function	Rassemble PluginCredential[] depuis tous les plugins enregistrés dans la config et résout leurs valeurs.
injectPluginTokensToEnv	function	Écrit les valeurs de tokens de plugin résolues dans process.env pour que les étapes de publish suivantes puissent les lire comme des variables d’environnement classiques.
ReleaseContext	type	Métadonnées de release transmises aux hooks afterRelease. Inclut packageName, version, tag, releaseUrl et assets.
ReleaseAsset	type	Un artefact uploadé : name, url, sha256 et platform structuré.
ParsedPlatform	type	Informations de plateforme structurées : raw, os, arch, vendor, abi, variant.
PreparedAsset	type	Artefact après compression et hachage, prêt à être uploadé.
TransformedAsset	type	Artefact après le hook transformAsset, avant la compression.
CompressedAsset	type	Artefact après l’étape compressAsset, avant le nommage.
UploadedAsset	type	Artefact après upload avec url et target.
ResolvedAsset	type	Artefact après la correspondance glob avec les informations de plateforme analysées.

import { defineConfig, type PubmPlugin } from "@pubm/core";

const plugin: PubmPlugin = {
  name: "announce",
  hooks: {
    afterPublish(ctx) {
      console.log("published", ctx.version);
    },
  },
};

export default defineConfig({
  plugins: [plugin],
});

Pipeline d’artefacts

Ces exports alimentent le pipeline d’artefacts de release et sont utiles aux auteurs de plugins et aux outils personnalisés.

Export	Nature	Rôle
parsePlatform	function	Analyser l’OS, l’architecture, l’ABI, la variante et le vendor depuis une chaîne de segment de chemin à l’aide des tables intégrées.
runAssetPipeline	function	Exécuter tout le pipeline d’artefacts (resolve, transform, compress, name, hash, checksums) à partir d’une config résolue et d’un ensemble de hooks.

import { parsePlatform, runAssetPipeline } from "@pubm/core";

// Analyser un segment de chemin ou une chaîne capturée
const platform = parsePlatform("darwin-arm64");
// { raw: "darwin-arm64", os: "darwin", arch: "arm64" }

const platform2 = parsePlatform("x86_64-unknown-linux-gnu");
// { raw: "x86_64-unknown-linux-gnu", os: "linux", arch: "x64", vendor: "unknown", abi: "gnu" }

Types du pipeline d’artefacts :

import type {
  ParsedPlatform,
  ReleaseContext,
  ReleaseAsset,
  ResolvedAsset,
  TransformedAsset,
  CompressedAsset,
  PreparedAsset,
  UploadedAsset,
} from "@pubm/core";

Voir Artefacts de release et Hooks du pipeline d’artefacts pour les guides d’utilisation.

Aides de changeset et de versioning

Les exports liés aux changesets vous permettent de construire des outils personnalisés autour de .pubm/changesets.

Export	Nature	Rôle
readChangesets / parseChangeset	functions	Lire et parser .pubm/changesets/*.md.
getStatus	function	Regrouper les changesets en attente par package.
discoverCurrentVersions / discoverPackageInfos	functions	Lire les noms et versions actuels des packages depuis le workspace.
calculateVersionBumps	function	Calculer les prochaines versions à partir des versions courantes et des changesets en attente.
generateChangesetId / generateChangesetContent / writeChangeset	functions	Créer de nouveaux fichiers changeset.
buildChangelogEntries / generateChangelog / writeChangelogToFile	functions	Construire la sortie du changelog à partir des changesets.
migrateFromChangesets	function	Copier les données héritées de .changeset/ dans .pubm/.
deleteChangesetFiles	function	Supprimer les fichiers changeset consommés.
parseChangelogSection	function	Reparser une section de changelog en données structurées.

Types liés importants :

Type	Rôle
Changeset	Fichier .md parsé avec id, summary et les releases de package.
Release	Une entrée de bump de package dans un changeset.
BumpType	"patch" | "minor" | "major".
Status / PackageStatus	État agrégé en attente renvoyé par getStatus().
VersionBump	Résultat de planification de version renvoyé par calculateVersionBumps().
ChangelogEntry / DependencyUpdate	Entrées de rendu du changelog.
PackageVersionInfo	Nom du package, version et chemin renvoyés par les aides de découverte.
MigrationResult	Objet résultat renvoyé par migrateFromChangesets().

import {
  calculateVersionBumps,
  discoverCurrentVersions,
  getStatus,
} from "@pubm/core";

const currentVersions = await discoverCurrentVersions(process.cwd());
const status = getStatus(process.cwd());
const nextVersions = calculateVersionBumps(currentVersions, process.cwd());

Aides de monorepo et de workspace

Ces exports sont utiles lorsque vous avez besoin de la même logique de découverte de workspace que celle utilisée en interne par pubm.

Export	Nature	Rôle
detectWorkspace	function	Détecter les workspaces pnpm, npm, Yarn, Bun, Cargo ou Deno à partir des fichiers du dépôt.
discoverPackages	function	Découvrir automatiquement les packages publiables et inférer les registries/écosystèmes.
buildDependencyGraph	function	Construire un graphe de dépendances interne à partir des métadonnées de package.
topologicalSort	function	Trier les nœuds du graphe pour que les dépendances viennent d’abord.
resolveGroups	function	Résoudre les groupes fixed/linked à partir d’une liste de packages découverts.
applyFixedGroup / applyLinkedGroup	functions	Appliquer la sémantique de groupe à la planification de version.
Git	class	Fine enveloppe autour des commandes Git utilisées par l’automatisation de release.

Types liés importants :

Type	Rôle
WorkspaceInfo	Type de workspace plus patterns d’inclusion/exclusion.
DiscoverOptions	Entrée pour discoverPackages().
DiscoveredPackage	Chemin de package, registries et écosystème détectés automatiquement.
PackageNode	Nœud d’entrée utilisé pour construire le graphe de dépendances.

import {
  buildDependencyGraph,
  discoverPackages,
  topologicalSort,
} from "@pubm/core";

const discovered = await discoverPackages({ cwd: process.cwd() });

const graph = buildDependencyGraph([
  {
    name: "@acme/core",
    version: "1.0.0",
    path: "packages/core",
    dependencies: { "@acme/utils": "^1.0.0" },
  },
  {
    name: "@acme/utils",
    version: "1.0.0",
    path: "packages/utils",
    dependencies: {},
  },
]);

const ordered = topologicalSort(graph);

Aides de validation et utilitaires

La racine du package exporte aussi les aides ci-dessous pour les intégrations d’outils.

Export	Nature	Rôle
validateEntryPoints	function	Vérifier les chemins main, module, types, exports et bin dans un manifest de package.
detectExtraneousFiles	function	Signaler les fichiers qui devraient généralement rester hors des artefacts de publication.
getPackageJson	function	Lire le package.json le plus proche, avec fallback optionnel vers jsr.json.
replaceVersion / replaceVersionAtPath	functions	Réécrire les versions de package dans les manifests.
version	function	Lire la version actuelle du package depuis package.json, jsr.json ou deno.json / deno.jsonc.
generateSnapshotVersion	function	Construire des versions snapshot à partir de base, tag, timestamp et d’un commit optionnel.
loadTokensFromDb	function	Charger les tokens de registry stockés, en respectant aussi les variables d’environnement correspondantes.
syncGhSecrets	function	Pousser les tokens de registry dans GitHub Secrets via gh secret set.
exec	function	Lancer un sous-processus et capturer stdout/stderr.
getPackageManager	function	Détecter le gestionnaire de paquets du workspace à partir des lockfiles.
detectRuntime / isBun	functions	Détecter le runtime courant.
notifyNewVersion	function	Vérifier s’il existe une version pubm plus récente et afficher une bannière de mise à jour.
consoleError	function	Formater et afficher les erreurs pubm.
PUBM_VERSION / PUBM_ENGINES	constants	Métadonnées du package exposées au runtime.

Types liés importants :

Type	Rôle
EntryPointError	Entrée de résultat de validation pour des chemins de manifest cassés.
ExtraneousFile	Entrée de résultat de validation pour des fichiers qui ne devraient pas être publiés.
SnapshotOptions	Entrée pour generateSnapshotVersion().
Runtime	"node" | "bun".

import {
  generateSnapshotVersion,
  loadTokensFromDb,
  validateEntryPoints,
} from "@pubm/core";

const nextSnapshot = generateSnapshotVersion({
  baseVersion: "1.4.0",
  tag: "snapshot",
  commit: "abc1234",
  template: "{base}-{tag}-{timestamp}-{commit}",
});

const entryPointErrors = validateEntryPoints(
  {
    main: "./dist/index.js",
    types: "./dist/index.d.ts",
  },
  process.cwd(),
);

const tokens = loadTokensFromDb(["npm", "jsr"]);

Politique d’export

Cette page documente la surface stable exportée aujourd’hui depuis la racine du package. Les fichiers internes sous packages/core/src/** peuvent exister, mais s’ils ne sont pas re-exportés depuis @pubm/core, ils doivent être considérés comme des détails d’implémentation privés.