State & Context Management
Relevant source files
The following files were used as context for generating this wiki page:
State and context management in pubm provides a centralized mechanism for managing configuration, runtime data, and versioning plans across the lifecycle of a package release. It ensures that components such as the CLI, core SDK, and plugins operate on a consistent, immutable set of initial parameters while allowing for a mutable runtime state to track progress, rollback actions, and versioning decisions.
Architecture Overview
The system revolves around the PubmContext object, which acts as the single source of truth during execution. This context combines static configuration (derived from files), user-provided options (from the CLI), and a dynamic runtime state.
The diagram above illustrates how various inputs are aggregated into the PubmContext, which then maintains a mutable Runtime state.
Sources: packages/core/tests/unit/context.test.ts:46-52
Core Components
The following table describes the primary structures involved in managing the state of the application:
| Component | Description | Mutability |
|---|---|---|
ResolvedPubmConfig | The final configuration object after merging defaults and user-defined pubm.config.ts. | Immutable (Frozen) |
ResolvedOptions | CLI flags and environment variables parsed at runtime. | Immutable (Frozen) |
PubmContext | The container object passed through tasks and plugin hooks. | Mutable (Reference) |
RuntimeState | Tracks dynamic execution data like versionPlan, rollback actions, and authentication tags. | Mutable |
Sources: packages/core/tests/unit/context.test.ts:52-58, packages/core/tests/unit/context.test.ts:98-105
Runtime State and Versioning Plans
A critical aspect of state management is the versionPlan, which determines how packages in a repository (especially monorepos) are bumped. This plan is generated during the versioning phase and stored in the runtime state for subsequent tasks like building and publishing.
Versioning Strategies
The context supports three primary versioning modes stored within the versionPlan:
- Single: Used for individual packages where a single version is applied.
- Fixed: All packages in a group share the same version.
- Independent: Each package is versioned separately based on its own changesets or commit history.
This class diagram represents the relationship between the global runtime state and the specific versioning plan.
Sources: packages/core/tests/unit/context.test.ts:121-149, packages/pubm/src/commands/version-cmd.ts:60-75
Version Resolution
The utility function getPackageVersion is used to extract the specific version for a package path from the current context, abstracting away the complexity of the versioning mode.
Sources: packages/core/tests/unit/context.test.ts:121-155
Rollback and Error Handling State
pubm manages a "Rollback Registry" within the runtime state. This allows the system to register "undo" actions as tasks complete. If a failure occurs, the system iterates through this registry to revert changes like git tags, remote releases, or published versions.
Rollback Registration Flow
When a task such as creating a GitHub Release succeeds, it registers a corresponding rollback function in the context.
The sequence shows how tasks contribute to the execution state for potential recovery.
Sources: packages/core/src/tasks/phases/push-release.ts:145-152, packages/core/src/tasks/phases/push-release.ts:241-247
Configuration Initialization
The initialization process (pubm init) populates the initial state by scanning the project and prompting the user. This state is then persisted into a pubm.config.ts file or used to generate CI workflows.
| Feature | Logic | File Reference |
|---|---|---|
| Monorepo Detection | Checks for workspace globs to set isMonorepo flag in context. | init-prompts.ts |
| Branch Detection | Uses git remote show to determine the default release branch. | init-prompts.ts |
| Strategy Selection | Prompts for "Fixed" vs "Independent" versioning. | init-prompts.ts |
Sources: packages/pubm/src/commands/init-prompts.ts:193-210, packages/pubm/src/commands/init-prompts.ts:310-325
Conditional State Persistence
pubm optimizes state management by only creating a configuration file if the detected project state differs from the system defaults.
Sources: packages/pubm/src/commands/init-prompts.ts:70-95
Context in the Release Pipeline
During the push and release phases, the PubmContext is utilized to resolve authentication tokens (like GITHUB_TOKEN) and metadata.
The flow demonstrates how the context guides the execution path based on available environmental state.
Sources: packages/core/src/tasks/phases/push-release.ts:85-115
Conclusion
State and context management in pubm ensures a predictable and recoverable release process. By isolating immutable configurations from mutable runtime data and providing a structured versioning plan, the system facilitates complex workflows like monorepo management and automated rollbacks with high reliability.