Core Architecture & Pipeline

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• packages/core/src/tasks/phases/push-release.ts
• packages/pubm/src/commands/version-cmd.ts
• packages/pubm/src/commands/init-workflows.ts
• packages/core/src/changeset/writer.ts
• packages/core/src/config/loader.ts
• packages/core/tests/unit/tasks/runner-coverage.test.ts

pubm is a CLI tool designed to orchestrate the publishing of packages to multiple registries simultaneously, including npm, JSR, and crates.io. Its core architecture centers on a task-based pipeline that handles preflight checks, versioning, testing, building, and multi-registry distribution with a built-in automatic rollback mechanism to ensure repository integrity on failure.

The system is built using a monorepo structure with Turborepo and Bun, separating concerns between a core SDK (@pubm/core) and the primary CLI package (pubm). It supports both interactive local environments and headless CI/CD environments through a specialized execution mode.

Sources: CLAUDE.md:5-15, website/src/i18n/landing.ts:46-55

Pipeline Execution Flow

The release pipeline follows a structured sequence of "phases" and "tasks" managed by a runner. The execution flow changes slightly depending on whether the tool is running in local mode or ci mode.

Lifecycle Phases

The pipeline is divided into distinct execution blocks:

1. Prerequisites & Preflight: Checks for clean git status, branch validity, and registry authentication.
2. Versioning: Analyzes changesets or conventional commits to calculate new versions and update manifest files.
3. Build & Test: Executes project-specific scripts to ensure code quality and generate artifacts.
4. Publish: Distributes packages to all configured registries in parallel (where supported).
5. Post-Publish: Handles git pushing, PR creation, and GitHub Release generation.

Versioning & Changeset System

pubm employs a sophisticated versioning system that can derive recommendations from multiple sources, primarily Changesets and Conventional Commits.

Changeset Workflow

Changesets are stored as Markdown files in the .pubm/changesets directory. Each file contains YAML frontmatter mapping packages to bump types (patch, minor, major) and a summary of the changes.

• Generation: Users create changesets via pubm changesets add.
• Analysis: The ChangesetSource scans the directory to calculate the next version for each package.
• Consumption: Once versions are bumped, the changeset files are deleted from the local filesystem.

Sources: packages/core/src/changeset/writer.ts:90-110, packages/pubm/src/commands/version-cmd.ts:43-65

Versioning Strategies

Strategy	Description
Single	Used for non-monorepo projects where a single version applies to the whole repository.
Fixed	In a monorepo, all packages are kept in sync with the same version number.
Independent	Packages in a monorepo are versioned separately based on their individual changes.

Sources: packages/core/tests/unit/tasks/runner-coverage.test.ts:435-460, packages/core/src/tasks/phases/push-release.ts:100-115

Registry & Ecosystem Abstraction

The architecture utilizes an "Ecosystem" and "Registry" abstraction to support multiple languages and platforms.

Ecosystems

The Ecosystem class handles manifest file interactions.

• JS Ecosystem: Manages package.json, jsr.json, and deno.json.
• Rust Ecosystem: Manages Cargo.toml.

Registry Integration

Registries are handled via a catalog system where each registry (npm, jsr, crates) provides a taskFactory to create publish and dry-run tasks.

Configuration Loading

Config files (pubm.config.ts, .js, etc.) are loaded dynamically. The core uses a bundled build process (leveraging Bun) to handle TypeScript and ESM imports even in varying environments.

Loading Logic

1. Search: Looks for pubm.config.ts, pubm.config.mjs, etc.
2. Bundling: If using Bun, it uses Bun.build to create a temporary executable version of the config.
3. Shim & Polyfill: Injects shims for modules like vitest/config to allow project-specific config sharing.
4. Execution: Runs the bundled config in a VM context if standard imports fail.

Sources: packages/core/src/config/loader.ts:11-35, packages/core/src/config/loader.ts:805-850

GitHub Integration & Workflows

pubm automates GitHub-specific release tasks, including tag pushing, Pull Request creation for version bumps, and Release notes generation.

Release Tasks

• Tagging: Creates tags based on the calculated versions (e.g., v1.0.0 or package@1.0.0).
• Push via PR: If a branch is protected, pubm can automatically create a new branch, push changes, and open a PR.
• GitHub Release: Uses the GitHub API to create a release, upload assets, and populate changelogs parsed from CHANGELOG.md.

Automated Workflows

The tool can generate GitHub Action YAML files for CI/CD integration:

• Release Workflow: Triggered on tags (single package) or branch pushes (monorepo).
• Changeset Check: Triggered on PRs to ensure developers have included a changeset file.

Sources: packages/core/src/tasks/phases/push-release.ts:35-85, packages/pubm/src/commands/init-workflows.ts:50-100

Summary

The pubm architecture is defined by its reliability and extensibility. By abstracting ecosystems and registries into a task-based pipeline, it provides a unified interface for complex release workflows. The integration of a robust rollback system and a flexible configuration loader makes it suitable for both simple single-package repositories and complex multi-language monorepos.