Package and Binary Distribution
Relevant source files
The following files were used as context for generating this wiki page:
The Package and Binary Distribution system in OhMyOpenCode manages the lifecycle of software releases, spanning from version bumping and automated changelog generation to multi-platform binary compilation and NPM publication. The project utilizes a multi-package architecture to support various operating systems and architectures, ensuring that users receive optimized binaries for their specific environments.
The distribution logic is primarily driven by automation scripts that interact with the Git history, the NPM registry, and the GitHub API. This ensures a consistent release process that includes automated version syncing across the main package and its platform-specific sub-packages.
Release Lifecycle and Automation
The release process is orchestrated through a central publication script that manages versioning, build steps, and deployment.
Versioning Strategy
OhMyOpenCode follows semantic versioning (SemVer). The publication script supports major, minor, and patch bumps. It also handles pre-release versions, specifically beta tags, by identifying previous beta iterations for accurate comparison and changelog generation.
The diagram above illustrates the sequential flow of the publication process from version discovery to final release.
Sources: script/publish.ts:13-25, script/publish.ts:47-68
Package Synchronization
Because the project supports multiple platforms, it maintains a set of platform-specific packages (e.g., darwin-arm64, linux-x64, windows-x64). The system ensures that the version of the main oh-my-opencode package remains in sync with these platform packages and their entries in the optionalDependencies section of the main manifest.
Sources: script/publish.ts:6-14, script/publish.ts:54-68
Build and Compilation
Before publication, the system executes a clean build of the core project and generates platform-specific binaries.
Binary Targets
The project targets seven distinct platform/architecture combinations. These are built using the build:binaries command, which prepares the specialized sub-packages located in the packages/ directory.
| Platform-Architecture | Package Name Suffix |
|---|---|
| macOS ARM64 | darwin-arm64 |
| macOS x64 | darwin-x64 |
| Linux x64 | linux-x64 |
| Linux ARM64 | linux-arm64 |
| Linux x64 (musl) | linux-x64-musl |
| Linux ARM64 (musl) | linux-arm64-musl |
| Windows x64 | windows-x64 |
Sources: script/publish.ts:6-14, script/publish.ts:257-268
Changelog and Release Notes
Automated changelog generation is a critical component of the distribution system, ensuring that every release is documented with its corresponding technical changes and community contributions.
Commit Analysis
The system filters Git logs to exclude non-user-facing commits such as chore:, ci:, and test:. It uses the gh api to compare the current HEAD against the previous release tag to identify meaningful changes.
Release Framing
For minor compatibility and stability releases, the system applies "Release Framing" logic. It analyzes which files were modified and prepends a summary of the release's impact based on specific file paths.
| Path Category | Impact Description |
|---|---|
src/index.ts, bin/platform.js | Rename transition and installation surface updates. |
src/tools/delegate-task | Task/tool behavior and runtime registration updates. |
.github/workflows | Workflow hardening and release sequencing. |
Sources: script/generate-changelog.ts:19-27, script/generate-changelog.ts:50-84
Distribution and Registry Publication
The final stage of the process involves pushing the compiled assets to the NPM registry and finalizing the GitHub release.
Multi-Package Batch Publication
To prevent OIDC (OpenID Connect) token expiration during CI runs, platform packages are published in batches (default batch size of 2). The main package is published last to ensure all dependencies are available in the registry first.
The sequence above shows the batch-based publication strategy used to manage registry interactions.
Sources: script/publish.ts:211-255, script/publish.ts:285-300
Error Handling and Republishing
The publication logic includes specific handling for registry conflicts. If a version already exists, the script can enter a republishMode where it skips existing packages and only attempts to upload missing platform-specific packages. This is particularly useful for recovering from partial failures during the batch publication process.
Sources: script/publish.ts:169-204
Conclusion
The Package and Binary Distribution module ensures that OhMyOpenCode is delivered as a robust, multi-platform tool. By automating the synchronization of sub-packages, generating context-aware changelogs, and managing the complexities of batch registry uploads, the system maintains high release velocity with minimal manual intervention.