Core SDK Reference

@pubm/core is the programmatic API for the pubm CLI. This page lists the public exports from the package root:

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

The package includes type declarations and both ESM/CJS entry points. Package metadata currently requires node >= 24.

Install

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

Release pipeline

pubm(options)

Runs the same release pipeline that powers the CLI.

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

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

pubm() accepts an Options object. The key fields are:

Field	Type	Purpose
version	string	Required release target such as patch, minor, major, or an explicit semver.
dryRun	boolean	Show the task plan without mutating Git state or publishing.
mode	"local" | "ci"	Execution mode: local (interactive) or ci (non-interactive, tag-based).
prepare	boolean	Run the preparation phase only (validate and dry-run publish checks).
publish	boolean	Run the publish phase only (publish from the latest tag).
releaseDraft	boolean	Create a draft GitHub Release instead of a published one.
branch	string	Require a specific branch before publishing.
anyBranch	boolean	Disable branch enforcement for one run.
tag	string	Publish under a dist-tag like latest, next, or beta.
packages	PackageConfig[]	Override auto-discovered packages.

For config-driven releases, pubm() loads pubm.config.*, resolves package discovery, and wires plugins before it runs the task graph.

Config helpers

Use these helpers to read or validate pubm.config.*.

Export	Kind	Purpose
defineConfig	function	Typed helper for authoring pubm.config.ts.
loadConfig	function	Load pubm.config.* from disk and return PubmConfig | null.
resolveConfig	function	Apply defaults, auto-discover packages, and normalize private registries.
PubmConfig	type	User-authored config shape.
ResolvedPubmConfig	type	Fully-resolved config returned by resolveConfig().
PackageConfig	type	Per-package config entry used by discovery and publish planning.

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;

Use PackageConfig to override per-package registries, ecosystem, build command, or test command:

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

Plugin API

Use the plugin exports to extend the publish pipeline with custom registries, ecosystems, lifecycle hooks, or CLI commands.

Export	Kind	Purpose
PubmPlugin	type	Top-level plugin contract.
PluginHooks	type	Lifecycle hooks such as beforeBuild, afterPublish, onError, afterRelease, and asset pipeline hooks.
HookFn / ErrorHookFn / AfterReleaseHookFn	type	Hook signatures.
PluginCommand / PluginSubcommand / PluginCommandOption	type	Custom CLI command model for plugins.
PluginRunner	class	Utility that executes hooks and collects registries/ecosystems from loaded plugins. Also exposes collectCredentials() and collectChecks() to gather credential descriptors and preflight checks from all registered plugins.
PluginCredential	type	Declarative descriptor for a token or secret required by a plugin. See Plugins API Reference.
PluginCheck	type	Descriptor for a preflight check contributed by a plugin. See Plugins API Reference.
PluginTaskContext	type	Listr2-agnostic wrapper passed to PluginCheck.task. Exposes output, title, and prompt().
GhSecretEntry	type	One entry returned by the GitHub Secrets sync helpers: { secretName: string; token: string }.
collectPluginCredentials	function	Gather PluginCredential[] from all plugins registered in the config and resolve their values.
injectPluginTokensToEnv	function	Write resolved plugin token values into process.env so subsequent publish steps can read them as plain env vars.
ReleaseContext	type	Release metadata passed to afterRelease hooks. Includes packageName, version, tag, releaseUrl, and assets.
ReleaseAsset	type	One uploaded asset: name, url, sha256, and structured platform.
ParsedPlatform	type	Structured platform info: raw, os, arch, vendor, abi, variant.
PreparedAsset	type	Asset after compression and hashing, ready for upload.
TransformedAsset	type	Asset after transformAsset hook, before compression.
CompressedAsset	type	Asset after compressAsset step, before naming.
UploadedAsset	type	Asset after upload with url and target.
ResolvedAsset	type	Asset after glob matching with parsed platform info.

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

Asset pipeline

These exports support the release asset pipeline and are useful for plugin authors and custom tooling.

Export	Kind	Purpose
parsePlatform	function	Parse OS, arch, ABI, variant, and vendor from a path segment string using the built-in tables.
runAssetPipeline	function	Run the full asset pipeline (resolve, transform, compress, name, hash, checksums) given a resolved config and hook set.

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

// Parse a path segment or capture string
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" }

Asset pipeline types:

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

See Release Assets and Asset Pipeline Hooks for usage guides.

Changeset and versioning helpers

These exports help you build custom tooling around .pubm/changesets.

Export	Kind	Purpose
readChangesets / parseChangeset	functions	Read and parse .pubm/changesets/*.md.
getStatus	function	Aggregate pending changesets by package.
discoverCurrentVersions / discoverPackageInfos	functions	Read current package names and versions from the workspace.
calculateVersionBumps	function	Compute next versions from current versions plus pending changesets.
generateChangesetId / generateChangesetContent / writeChangeset	functions	Create new changeset files.
buildChangelogEntries / generateChangelog / writeChangelogToFile	functions	Build changelog output from changesets.
migrateFromChangesets	function	Copy legacy .changeset/ data into .pubm/.
deleteChangesetFiles	function	Remove consumed changeset files.
parseChangelogSection	function	Parse a changelog section back into structured data.

Important related types:

Type	Purpose
Changeset	Parsed .md file with id, summary, and package releases.
Release	One package bump entry inside a changeset.
BumpType	"patch" | "minor" | "major".
Status / PackageStatus	Aggregated pending state from getStatus().
VersionBump	Version planning result from calculateVersionBumps().
ChangelogEntry / DependencyUpdate	Changelog rendering inputs.
PackageVersionInfo	Package name, version, and path returned by discovery helpers.
MigrationResult	Result object returned by 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());

Monorepo and workspace helpers

These exports are useful when you need the same workspace discovery logic that pubm uses internally.

Export	Kind	Purpose
detectWorkspace	function	Detect pnpm, npm, Yarn, Bun, Cargo, or Deno workspaces from repository files.
discoverPackages	function	Auto-discover publishable packages and infer registries/ecosystems.
buildDependencyGraph	function	Build an internal dependency graph from package metadata.
topologicalSort	function	Sort graph nodes so dependencies come first.
resolveGroups	function	Resolve fixed/linked groups against a discovered package list.
applyFixedGroup / applyLinkedGroup	functions	Apply group semantics to version planning.
Git	class	Thin wrapper around Git commands used by release automation.

Important related types:

Type	Purpose
WorkspaceInfo	Workspace type plus include/exclude patterns.
DiscoverOptions	Input for discoverPackages().
DiscoveredPackage	Auto-detected package path, registries, and ecosystem.
PackageNode	Input node used for dependency graph building.

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);

Validation and utility helpers

The package root also exports these helpers for tooling integrations.

Export	Kind	Purpose
validateEntryPoints	function	Check main, module, types, exports, and bin paths in a package manifest.
detectExtraneousFiles	function	Flag files that should usually stay out of publish artifacts.
getPackageJson	function	Read the nearest package.json, with optional jsr.json fallback.
replaceVersion / replaceVersionAtPath	functions	Rewrite package versions in manifests.
version	function	Read the current package version from package.json, jsr.json, or deno.json / deno.jsonc.
generateSnapshotVersion	function	Build snapshot versions from base, tag, timestamp, and optional commit.
loadTokensFromDb	function	Load stored registry tokens, also honoring matching env vars.
syncGhSecrets	function	Push registry tokens into GitHub Secrets via gh secret set.
exec	function	Spawn a subprocess and capture stdout/stderr.
getPackageManager	function	Detect the workspace package manager from lockfiles.
detectRuntime / isBun	functions	Detect the current runtime.
notifyNewVersion	function	Check for a newer published pubm version and print an update banner.
consoleError	function	Format and print pubm errors.
PUBM_VERSION / PUBM_ENGINES	constants	Package metadata exposed at runtime.

Important related types:

Type	Purpose
EntryPointError	Validation result entry for broken manifest paths.
ExtraneousFile	Validation result entry for files that should not be published.
SnapshotOptions	Input for 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"]);

Export policy

This page documents the stable surface exported from the package root. Internal files under packages/core/src/** may exist, but if they are not re-exported from @pubm/core, they should be treated as private implementation details.