External Version Sync Plugin

Relevant source files

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

• packages/plugins/plugin-external-version-sync/src/index.ts
• plugins/pubm-plugin/skills/publish-setup/references/official-plugins.md
• packages/plugins/plugin-external-version-sync/tests/unit/plugin.test.ts
• packages/plugins/plugin-external-version-sync/tests/integration/external-version-sync.test.ts
• packages/pubm/tests/unit/commands/sync.test.ts
• packages/core/src/tasks/phases/version.ts
• packages/plugins/plugin-external-version-sync/package.json

The External Version Sync Plugin (@pubm/plugin-external-version-sync) is an official plugin for the pubm ecosystem designed to maintain version consistency across non-manifest files. It automates the updating of version strings in files such as READMEs, documentation examples, source code constants, and application manifests (e.g., plugin.json) immediately after a version bump occurs in the primary package manifests.

Sources: CLAUDE.md:14, plugins/pubm-plugin/skills/publish-setup/references/official-plugins.md:15-25

Architecture and Integration

The plugin integrates with the pubm core pipeline via the afterVersion hook. This hook is triggered during the versioning phase, after package manifest versions have been updated but before the changes are committed to the repository.

Sources: packages/core/src/tasks/phases/version.ts:74, packages/plugins/plugin-external-version-sync/src/index.ts:21

Execution Flow

1. Context Resolution: The plugin extracts the versionPlan from the PubmContext to determine the target version.
2. Target Iteration: It iterates through a configured list of SyncTarget objects.
3. Backup and Rollback Registration: For each target file, the plugin reads the current content and registers a rollback function with ctx.runtime.rollback. This ensures that if the publishing pipeline fails later, the original file contents are restored.
4. File Synchronization: It utilizes internal utilities to locate and replace version strings based on either JSON paths or Regular Expression patterns.
5. Error Aggregation: If updates to any targets fail, the plugin collects the errors and throws an aggregated exception at the end of the process.

Sources: packages/plugins/plugin-external-version-sync/src/index.ts:22-68, packages/plugins/plugin-external-version-sync/tests/unit/plugin.test.ts:149-166

Data Flow Diagram

The diagram above illustrates the sequence of operations within the afterVersion hook.
Sources: packages/plugins/plugin-external-version-sync/src/index.ts:21-68, packages/core/src/tasks/phases/version.ts:74

Configuration and Usage

The plugin is configured via ExternalVersionSyncOptions, which defines the files to be updated and how to identify the version string within them.

Target Types

The plugin supports two primary methods for identifying version locations:

Target Type	Description	Configuration Fields
JSON	Updates a value at a specific path in a JSON file.	file (string), jsonPath (string)
Regex	Replaces content matching a pattern. The pattern should typically include a capture group for the version.	file (string), pattern (RegExp)

Sources: plugins/pubm-plugin/skills/publish-setup/references/official-plugins.md:46-60, packages/plugins/plugin-external-version-sync/src/index.ts:11-16

Independent Versioning Support

In monorepos using independent versioning, the plugin requires a version callback. This function allows developers to specify which package's version should be used for the synchronization of a particular target.

Sources: plugins/pubm-plugin/skills/publish-setup/references/official-plugins.md:62-72, packages/plugins/plugin-external-version-sync/tests/integration/external-version-sync.test.ts:124-143

Example Configuration

import { externalVersionSync } from '@pubm/plugin-external-version-sync'

export default defineConfig({
  plugins: [
    externalVersionSync({
      targets: [
        { file: 'manifest.json', jsonPath: 'metadata.version' },
        { file: 'README.md', pattern: /pubm@([\w.-]+)/g }
      ],
      // Required for independent mode
      version: (packages) => packages.get('packages/core') ?? ''
    }),
  ],
})

Sources: plugins/pubm-plugin/skills/publish-setup/references/official-plugins.md:74-88

Discovery Mechanism

The plugin functionality is complemented by a discovery command provided by the pubm CLI. Running pubm sync --discover initiates a recursive scan of the project directory to identify potential version references that are not currently managed by standard manifest files.

Discovery Logic

• JSON Scanning: Scans for keys like version or ver in JSON files (excluding package.json and jsr.json).
• Pattern Matching: Searches text files for strings matching common versioning patterns (e.g., v1.2.3, @version 1.2.3).
• Exclusions: Automatically ignores node_modules, standard lock files, and hidden directories (except .claude-plugin).

Sources: packages/pubm/tests/unit/commands/sync.test.ts:12-140, plugins/pubm-plugin/skills/publish-setup/references/official-plugins.md:37-44

Resilience and Rollback

To maintain repository integrity during failed releases, the plugin implements a strictly managed rollback strategy.

The diagram above shows the sequence of backup and restoration operations.
Sources: packages/plugins/plugin-external-version-sync/src/index.ts:47-57, packages/plugins/plugin-external-version-sync/tests/unit/plugin.test.ts:149-166

Failure Handling

• Error Isolation: If one target fails to update (e.g., file not found), the plugin continues attempting to update all other targets before reporting the failure.
• Aggregated Exceptions: If any updates fail, the plugin throws an Error containing a list of all failed targets and their specific error messages.

Sources: packages/plugins/plugin-external-version-sync/src/index.ts:59-67, packages/plugins/plugin-external-version-sync/tests/unit/plugin.test.ts:107-121

Conclusion

The External Version Sync Plugin provides a robust mechanism for keeping peripheral project documentation and manifests in sync with the primary package version. By utilizing the afterVersion hook and integrating with pubm's native rollback system, it ensures that version propagation is both automated and safe for production workflows.