Preflight & Validation

Relevant source files

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

• packages/core/src/tasks/prerequisites-check.ts
• packages/core/src/tasks/required-conditions-check.ts
• packages/core/src/tasks/preflight.ts
• packages/core/tests/unit/tasks/prerequisites-check.test.ts
• packages/core/tests/unit/tasks/runner-coverage.test.ts
• packages/core/src/i18n/locales/en.json

The Preflight & Validation system in pubm is a multi-layered safety mechanism designed to ensure deployment reliability. It verifies the environment, project state, and credentials before any destructive actions—such as version bumping or publishing—are performed. This system prevents common release failures caused by dirty working trees, outdated local history, or missing registry authentication.

The validation logic is primarily organized into three major task groups: Prerequisites, Required Conditions, and Preflight (Credential) checks. These tasks run sequentially during the local release mode or are split across prepare and publish phases in CI environments.

Prerequisites Check

The Prerequisites check focuses on the integrity of the Git repository and the local environment. It ensures that the developer is on the correct branch and that the local state matches the remote state.

Core Validation Logic

• Branch Verification: Ensures the current HEAD matches the configured release branch (e.g., main). If a mismatch is detected, the system prompts to switch branches.
• Remote History Check: Executes git fetch to check for updates and verifies if the local branch is behind the remote.
• Working Tree Cleanliness: Checks if there are uncommitted or unstaged changes. A "dirty" working tree is a critical failure unless explicitly skipped by the user.
• Commit History: Verifies that new commits exist since the last Git tag to avoid redundant releases.

Sources: packages/core/src/tasks/prerequisites-check.ts, packages/core/tests/unit/tasks/prerequisites-check.test.ts

Prerequisites Flow

The following diagram illustrates the sequential checks performed during the prerequisites phase:

The system utilizes listr2 to provide interactive progress and prompts for these subtasks.
Sources: packages/core/src/tasks/prerequisites-check.ts:1-50

Required Conditions Check

Required Conditions are technical necessities for the execution of pubm tasks. While Prerequisites focus on the "State," Conditions focus on "Capabilities."

Check	Description
Registry Availability	Pings configured registries (npm, JSR, crates.io) to ensure they are reachable.
Script Verification	Checks if required npm scripts (like test or build) are defined in package.json.
Git Version	Ensures the installed Git CLI meets the minimum version requirements.
Authentication	Validates that the user is logged into the respective registries or has tokens available.

Sources: packages/core/src/tasks/required-conditions-check.ts, packages/core/src/i18n/locales/en.json

Registry Validation Flow

For every target registry, the system verifies connectivity and authentication:

Preflight & Credential Collection

The Preflight phase is critical for CI/CD environments and local automated releases. It manages the collection and injection of sensitive tokens.

Token Management

In CI mode, specifically during the prepare phase, the system:

1. Collects Tokens: Retrieves tokens for npm, JSR, or other registries from environment variables (e.g., NODE_AUTH_TOKEN, JSR_TOKEN).
2. Validates Stored Tokens: Verifies if existing tokens are still valid.
3. Syncs to GitHub Secrets: Optionally synchronizes local tokens to GitHub repository secrets using the gh CLI for subsequent CI runs.
4. Credential Injection: Injects collected tokens into the process environment so they are available to underlying tools like npm publish or cargo publish.

Sources: packages/core/src/tasks/preflight.ts:1-60, packages/core/tests/unit/tasks/runner-coverage.test.ts:400-450

Credential Handling Logic

Local vs. CI Validation Behavior

Validation behavior adapts based on the execution mode to accommodate different environments.

Feature	Local Mode	CI Mode (prepare)	CI Mode (publish)
Interactivity	Fully interactive prompts	Non-interactive (fails on missing info)	Non-interactive
Prerequisites	Branch, Remote, Tree checks	Limited checks	Skipped (assumes prepare verified)
Token Handling	Uses local logins/keyring	Collects from Env/Secrets	Injects into environment
Rollback	Interactive confirmation	Automatic on failure	Automatic on failure

Sources: packages/core/tests/unit/tasks/runner-coverage.test.ts, packages/core/src/tasks/preflight.ts

Error Handling and Rollback

When a validation fails, the system triggers an onError hook. If changes were already made (e.g., in a dry-run scenario or failed publish), the RollbackTracker identifies registered recovery actions.

Significant error messages defined in the system include:

• error.prerequisites.wrongBranch: Triggered when the current branch does not match the release target.
• error.conditions.testScriptMissing: Triggered when the build/test script defined in configuration is missing from package.json.
• error.npm.noAuthToken: Triggered in CI when NODE_AUTH_TOKEN is missing.

Sources: packages/core/src/i18n/locales/en.json, packages/core/tests/unit/tasks/runner-coverage.test.ts:1000-1050

Summary

The Preflight & Validation system acts as the "Checklist" for pubm. By enforcing strict prerequisites and required conditions, it ensures that once the publishing process begins, the environment is fully capable of completing it successfully. In CI environments, this logic is split to allow for credential preparation before the actual build and release execution, maintaining high security and reliability standards.