https://github.com/openai/codex/pull/11318 introduced logic to publish platform artifacts as separate npm packages (for example,
`@openai/codex-darwin-arm64`, `@openai/codex-linux-x64`, etc.). That requires provisioning and
maintaining multiple package entries in npm, which would be nice to avoid.
We still need to keep the package-size mitigation (platform-specific payloads), but we want that
layout to live under a single npm package namespace (`@openai/codex`) using dist-tags.
We also need to preserve pre-release workflows where users install `@openai/codex@alpha` and get
platform-appropriate binaries.
## Release Strategy (New Scheme)
We publish **one npm package name for Codex binaries** (`@openai/codex`) and use **dist-tags** to select platform-specific payloads.
This avoids creating separate platform package names while keeping the package size split by platform.
### What gets published
#### Mainline release (`x.y.z`)
- `@openai/codex@latest` (meta package)
- `@openai/codex@darwin-arm64`
- `@openai/codex@darwin-x64`
- `@openai/codex@linux-arm64`
- `@openai/codex@linux-x64`
- `@openai/codex@win32-arm64`
- `@openai/codex@win32-x64`
- `@openai/codex-responses-api-proxy@latest`
- `@openai/codex-sdk@latest`
#### Alpha release (`x.y.z-alpha.N`)
- `@openai/codex@alpha` (meta package)
- `@openai/codex@alpha-darwin-arm64`
- `@openai/codex@alpha-darwin-x64`
- `@openai/codex@alpha-linux-arm64`
- `@openai/codex@alpha-linux-x64`
- `@openai/codex@alpha-win32-arm64`
- `@openai/codex@alpha-win32-x64`
- `@openai/codex-responses-api-proxy@alpha`
- `@openai/codex-sdk@alpha`
### Important note
**Note:** Because we never created the new packages on npm for, e.g., `@openai/codex-darwin-arm64`, since #11318 was merged, there are no npm packages to "clean up" as a result of this change.
## What changed
### 1. Stage platform tarballs as `@openai/codex` with platform-specific versions
File: `codex-cli/scripts/build_npm_package.py`
- Added `CODEX_NPM_NAME = "@openai/codex"` and platform metadata `npm_tag` values:
- `darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64`, `win32-arm64`, `win32-x64`
- For platform package staging (`codex-<platform>` inputs), switched generated `package.json` from:
- `name = @openai/codex-<platform>`
to:
- `name = @openai/codex`
- Added `compute_platform_package_version(version, platform_tag)` to make platform tarball versions unique
(`<release-version>-<platform-tag>`), because npm does not allow publishing the same `name@version`
repeatedly for multiple platform artifacts.
### 2. Point meta package optional dependencies at dist-tags on `@openai/codex`
File: `codex-cli/scripts/build_npm_package.py`
- Updated `optionalDependencies` generation for the main `codex` package to use npm alias syntax:
- key remains alias package name (e.g. `@openai/codex-darwin-arm64`), preserving runtime lookup behavior
- value now resolves to `@openai/codex` by dist-tag
- Stable releases now emit:
- `npm:@openai/codex@darwin-arm64`, etc.
- Alpha releases (`x.y.z-alpha.N`) now emit:
- `npm:@openai/codex@alpha-darwin-arm64`, etc.
### 3. Publish with per-tarball dist-tags in release CI
File: `.github/workflows/rust-release.yml`
- Reworked npm publish step to derive publish tag per tarball filename:
- platform tarballs publish with `<platform>` tags for stable releases
- platform tarballs publish with `alpha-<platform>` tags for alpha releases
- top-level tarballs (`codex`, `codex-responses-api-proxy`, `codex-sdk`) continue using the release tag policy
(`latest` implicit for stable, `alpha` for alpha)
- Added fail-fast behavior for unexpected tarball names to avoid silent mispublishes.
### 4. Documentation update
File: `codex-cli/scripts/README.md`
- Updated release staging description to reflect that platform-native variants are published as
dist-tagged `@openai/codex` artifacts rather than separate npm package names.
## Resulting behavior
- Mainline release:
- `@openai/codex@latest` resolves meta package
- meta package optional deps reference `@openai/codex@<platform-tag>`
- Alpha release:
- users can continue installing `@openai/codex@alpha`
- alpha meta package optional deps reference `@openai/codex@alpha-<platform-tag>`
This preserves platform-specific payload distribution while eliminating the need to manage a separate npm
package per platform.
## Validation notes
- Verified staged `package.json` output for stable and alpha meta packages includes expected alias targets.
- Verified staged platform package manifests are `name=@openai/codex` with unique platform-suffixed versions.
- Verified release publish tag derivation logic maps tarball names to expected stable and alpha platform tags.
There was a bit of copypasta I put up with when were publishing two
packages to npm, but now that it's three, I created some more scripts to
consolidate things.
With this change, I ran:
```shell
./scripts/stage_npm_packages.py --release-version 0.43.0-alpha.8 --package codex --package codex-responses-api-proxy --package codex-sdk
```
Indeed when it finished, I ended up with:
```shell
$ tree dist
dist
└── npm
├── codex-npm-0.43.0-alpha.8.tgz
├── codex-responses-api-proxy-npm-0.43.0-alpha.8.tgz
└── codex-sdk-npm-0.43.0-alpha.8.tgz
$ tar tzvf dist/npm/codex-sdk-npm-0.43.0-alpha.8.tgz
-rwxr-xr-x 0 0 0 25476720 Oct 26 1985 package/vendor/aarch64-apple-darwin/codex/codex
-rwxr-xr-x 0 0 0 29871400 Oct 26 1985 package/vendor/aarch64-unknown-linux-musl/codex/codex
-rwxr-xr-x 0 0 0 28368096 Oct 26 1985 package/vendor/x86_64-apple-darwin/codex/codex
-rwxr-xr-x 0 0 0 36029472 Oct 26 1985 package/vendor/x86_64-unknown-linux-musl/codex/codex
-rw-r--r-- 0 0 0 10926 Oct 26 1985 package/LICENSE
-rw-r--r-- 0 0 0 30187520 Oct 26 1985 package/vendor/aarch64-pc-windows-msvc/codex/codex.exe
-rw-r--r-- 0 0 0 35277824 Oct 26 1985 package/vendor/x86_64-pc-windows-msvc/codex/codex.exe
-rw-r--r-- 0 0 0 4842 Oct 26 1985 package/dist/index.js
-rw-r--r-- 0 0 0 1347 Oct 26 1985 package/package.json
-rw-r--r-- 0 0 0 9867 Oct 26 1985 package/dist/index.js.map
-rw-r--r-- 0 0 0 12 Oct 26 1985 package/README.md
-rw-r--r-- 0 0 0 4287 Oct 26 1985 package/dist/index.d.ts
```
We try to ensure ripgrep (`rg`) is provided with Codex.
- For `brew`, we declare it as a dependency of our formula:
08d82d8b00/Formula/c/codex.rb (L24)
- For `npm`, we declare `@vscode/ripgrep` as a dependency, which
installs the platform-specific binary as part of a `postinstall` script:
fdb8dadcae/codex-cli/package.json (L22)
- Users who download the CLI directly from GitHub Releases are on their
own.
In practice, I have seen `@vscode/ripgrep` fail on occasion. Here is a
trace from a GitHub workflow:
```
npm error code 1
npm error path /Users/runner/hostedtoolcache/node/20.19.5/arm64/lib/node_modules/@openai/codex/node_modules/@vscode/ripgrep
npm error command failed
npm error command sh -c node ./lib/postinstall.js
npm error Finding release for v13.0.0-13
npm error GET https://api.github.com/repos/microsoft/ripgrep-prebuilt/releases/tags/v13.0.0-13
npm error Deleting invalid download cache
npm error Download attempt 1 failed, retrying in 2 seconds...
npm error Finding release for v13.0.0-13
npm error GET https://api.github.com/repos/microsoft/ripgrep-prebuilt/releases/tags/v13.0.0-13
npm error Deleting invalid download cache
npm error Download attempt 2 failed, retrying in 4 seconds...
npm error Finding release for v13.0.0-13
npm error GET https://api.github.com/repos/microsoft/ripgrep-prebuilt/releases/tags/v13.0.0-13
npm error Deleting invalid download cache
npm error Download attempt 3 failed, retrying in 8 seconds...
npm error Finding release for v13.0.0-13
npm error GET https://api.github.com/repos/microsoft/ripgrep-prebuilt/releases/tags/v13.0.0-13
npm error Deleting invalid download cache
npm error Download attempt 4 failed, retrying in 16 seconds...
npm error Finding release for v13.0.0-13
npm error GET https://api.github.com/repos/microsoft/ripgrep-prebuilt/releases/tags/v13.0.0-13
npm error Deleting invalid download cache
npm error Error: Request failed: 403
```
To eliminate this error, this PR changes things so that we vendor the
`rg` binary into https://www.npmjs.com/package/@openai/codex so it is
guaranteed to be included when a user runs `npm i -g @openai/codex`.
The downside of this approach is the increase in package size: we
include the `rg` executable for six architectures (in addition to the
six copies of `codex` we already include). In a follow-up, I plan to add
support for "slices" of our npm module, so that soon users will be able
to do:
```
npm install -g @openai/codex@aarch64-apple-darwin
```
Admittedly, this is a sizable change and I tried to clean some things up
in the process:
- `install_native_deps.sh` has been replaced by `install_native_deps.py`
- `stage_release.sh` and `stage_rust_release.py` has been replaced by
`build_npm_package.py`
We now vendor in a DotSlash file for ripgrep (as a modest attempt to
facilitate local testing) and then build up the extension by:
- creating a temp directory and copying `package.json` over to it with
the target value for `"version"`
- finding the GitHub workflow that corresponds to the
`--release-version` and copying the various `codex` artifacts to
respective `vendor/TARGET_TRIPLE/codex` folder
- downloading the `rg` artifacts specified in the DotSlash file and
copying them over to the respective `vendor/TARGET_TRIPLE/path` folder
- if `--pack-output` is specified, runs `npm pack` on the temp directory
To test, I downloaded the artifact produced by this CI job:
https://github.com/openai/codex/actions/runs/17961595388/job/51085840022?pr=3660
and verified that `node ./bin/codex.js 'which -a rg'` worked as
intended.
It appears that `0.5.0` was built with `stage_release.sh` instead of
`stage_rust_release.py`, so add docs to clarify this and recommend
running `--version` on the release candidate to verify the right thing
was built.
