chore: introduce new --native flag to Node module release process (#844)

This PR introduces an optional build flag, `--native`, that will build a
version of the Codex npm module that:

- Includes both the Node.js and native Rust versions (for Mac and Linux)
- Will run the native version if `CODEX_RUST=1` is set
- Runs the TypeScript version otherwise

Note this PR also updates the workflow URL to
https://github.com/openai/codex/actions/runs/14872557396, as that is a
build from today that includes everything up through
#843.

Test Plan:

In `~/code/codex/codex-cli`, I ran:

```
pnpm stage-release --native
```

The end of the output was:

```
Staged version 0.1.2505121317 for release in /var/folders/wm/f209bc1n2bd_r0jncn9s6j_00000gp/T/tmp.xd2p5ETYGN
Test Node:
    node /var/folders/wm/f209bc1n2bd_r0jncn9s6j_00000gp/T/tmp.xd2p5ETYGN/bin/codex.js --help
Test Rust:
    CODEX_RUST=1 node /var/folders/wm/f209bc1n2bd_r0jncn9s6j_00000gp/T/tmp.xd2p5ETYGN/bin/codex.js --help
Next:  cd "/var/folders/wm/f209bc1n2bd_r0jncn9s6j_00000gp/T/tmp.xd2p5ETYGN" && npm publish --tag native
```

I verified that running each of these commands ran the expected version
of Codex.

While here, I also added `bin` to the `files` list in `package.json`,
which should have been done as part of
#757, as that added new entries to
`bin` that were matched by `.gitignore` but should have been included in
a release.

Author: bolinfest

README.md

@@ -652,17 +652,21 @@ The **DCO check** blocks merges until every commit in the PR carries the footer
 
 ### Releasing `codex`
 
-To publish a new version of the CLI, run the following in the `codex-cli` folder to stage the release in a temporary directory:
+To publish a new version of the CLI you first need to stage the npm package. A
+helper script in `codex-cli/scripts/` does all the heavy lifting. Inside the
+`codex-cli` folder run:
 
-```
+```bash
+# Classic, JS implementation that includes small, native binaries for Linux sandboxing.
 pnpm stage-release
-```
 
-Note you can specify the folder for the staged release:
-
-```
+# Optionally specify the temp directory to reuse between runs.
 RELEASE_DIR=$(mktemp -d)
-pnpm stage-release "$RELEASE_DIR"
+pnpm stage-release --tmp "$RELEASE_DIR"
+
+# "Fat" package that additionally bundles the native Rust CLI binaries for
+# Linux. End-users can then opt-in at runtime by setting CODEX_RUST=1.
+pnpm stage-release --native
 ```
 
 Go to the folder where the release is staged and verify that it works as intended. If so, run the following from the temp folder:

codex-cli/.eslintrc.cjs

@@ -1,6 +1,6 @@
 module.exports = {
   root: true,
-  env: { browser: true, es2020: true },
+  env: { browser: true, node: true, es2020: true },
   extends: [
     "eslint:recommended",
     "plugin:@typescript-eslint/recommended",

codex-cli/bin/codex.js

@@ -1,17 +1,89 @@
 #!/usr/bin/env node
+// Unified entry point for the Codex CLI.
+/*
+ * Behavior
+ * =========
+ *   1. By default we import the JavaScript implementation located in
+ *      dist/cli.js.
+ *
+ *   2. Developers can opt-in to a pre-compiled Rust binary by setting the
+ *      environment variable CODEX_RUST to a truthy value (`1`, `true`, etc.).
+ *      When that variable is present we resolve the correct binary for the
+ *      current platform / architecture and execute it via child_process.
+ *
+ *      If the CODEX_RUST=1 is specified and there is no native binary for the
+ *      current platform / architecture, an error is thrown.
+ */
 
-// Unified entry point for Codex CLI on all platforms
-// Dynamically loads the compiled ESM bundle in dist/cli.js
+import { spawnSync } from "child_process";
+import path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
 
-import path from 'path';
-import { fileURLToPath, pathToFileURL } from 'url';
+// Determine whether the user explicitly wants the Rust CLI.
+const wantsNative =
+  process.env.CODEX_RUST != null
+    ? ["1", "true", "yes"].includes(process.env.CODEX_RUST.toLowerCase())
+    : false;
+
+// Try native binary if requested.
+if (wantsNative) {
+  const { platform, arch } = process;
+
+  let targetTriple = null;
+  switch (platform) {
+    case "linux":
+      switch (arch) {
+        case "x64":
+          targetTriple = "x86_64-unknown-linux-musl";
+          break;
+        case "arm64":
+          targetTriple = "aarch64-unknown-linux-gnu";
+          break;
+        default:
+          break;
+      }
+      break;
+    case "darwin":
+      switch (arch) {
+        case "x64":
+          targetTriple = "x86_64-apple-darwin";
+          break;
+        case "arm64":
+          targetTriple = "aarch64-apple-darwin";
+          break;
+        default:
+          break;
+      }
+      break;
+    default:
+      break;
+  }
+
+  if (!targetTriple) {
+    throw new Error(`Unsupported platform: ${platform} (${arch})`);
+  }
+
+  // __dirname equivalent in ESM
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = path.dirname(__filename);
+
+  const binaryPath = path.join(__dirname, "..", "bin", `codex-${targetTriple}`);
+  const result = spawnSync(binaryPath, process.argv.slice(2), {
+    stdio: "inherit",
+  });
+
+  const exitCode = typeof result.status === "number" ? result.status : 1;
+  process.exit(exitCode);
+}
+
+// Fallback: execute the original JavaScript CLI.
 
 // Determine this script's directory
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 // Resolve the path to the compiled CLI bundle
-const cliPath = path.resolve(__dirname, '../dist/cli.js');
+const cliPath = path.resolve(__dirname, "../dist/cli.js");
 const cliUrl = pathToFileURL(cliPath).href;
 
 // Load and execute the CLI
@@ -21,7 +93,6 @@ const cliUrl = pathToFileURL(cliPath).href;
   } catch (err) {
     // eslint-disable-next-line no-console
     console.error(err);
-    // eslint-disable-next-line no-undef
     process.exit(1);
   }
 })();

codex-cli/package.json

@@ -23,6 +23,7 @@
     "stage-release": "./scripts/stage_release.sh"
   },
   "files": [
+    "bin",
     "dist"
   ],
   "dependencies": {

codex-cli/scripts/install_native_deps.sh

@@ -1,20 +1,44 @@
-#!/bin/bash
+#!/usr/bin/env bash
 
-# Copy the Linux sandbox native binaries into the bin/ subfolder of codex-cli/.
+# Install native runtime dependencies for codex-cli.
 #
-# Usage:
-#   ./scripts/install_native_deps.sh [CODEX_CLI_ROOT]
+# By default the script copies the sandbox binaries that are required at
+# runtime. When called with the --full-native flag, it additionally
+# bundles pre-built Rust CLI binaries so that the resulting npm package can run
+# the native implementation when users set CODEX_RUST=1.
 #
-# Arguments
-#   [CODEX_CLI_ROOT] – Optional.  If supplied, it should be the codex-cli
-#                      folder that contains the package.json for @openai/codex.
+# Usage
+#   install_native_deps.sh [RELEASE_ROOT] [--full-native]
 #
-# When no argument is given we assume the script is being run directly from a
-# development checkout. In that case we install the binaries into the
-# repository’s own `bin/` directory so that the CLI can run locally.
+# The optional RELEASE_ROOT is the path that contains package.json.  Omitting
+# it installs the binaries into the repository's own bin/ folder to support
+# local development.
 
 set -euo pipefail
 
+# ------------------
+# Parse arguments
+# ------------------
+
+DEST_DIR=""
+INCLUDE_RUST=0
+
+for arg in "$@"; do
+  case "$arg" in
+    --full-native)
+      INCLUDE_RUST=1
+      ;;
+    *)
+      if [[ -z "$DEST_DIR" ]]; then
+        DEST_DIR="$arg"
+      else
+        echo "Unexpected argument: $arg" >&2
+        exit 1
+      fi
+      ;;
+  esac
+done
+
 # ----------------------------------------------------------------------------
 # Determine where the binaries should be installed.
 # ----------------------------------------------------------------------------
@@ -41,7 +65,7 @@ mkdir -p "$BIN_DIR"
 # Until we start publishing stable GitHub releases, we have to grab the binaries
 # from the GitHub Action that created them. Update the URL below to point to the
 # appropriate workflow run:
-WORKFLOW_URL="https://github.com/openai/codex/actions/runs/14763725716"
+WORKFLOW_URL="https://github.com/openai/codex/actions/runs/14950726936"
 WORKFLOW_ID="${WORKFLOW_URL##*/}"
 
 ARTIFACTS_DIR="$(mktemp -d)"
@@ -50,12 +74,26 @@ trap 'rm -rf "$ARTIFACTS_DIR"' EXIT
 # NB: The GitHub CLI `gh` must be installed and authenticated.
 gh run download --dir "$ARTIFACTS_DIR" --repo openai/codex "$WORKFLOW_ID"
 
-# Decompress the two target architectures.
+# Decompress the artifacts for Linux sandboxing.
 zstd -d "$ARTIFACTS_DIR/x86_64-unknown-linux-musl/codex-linux-sandbox-x86_64-unknown-linux-musl.zst" \
      -o "$BIN_DIR/codex-linux-sandbox-x64"
 
 zstd -d "$ARTIFACTS_DIR/aarch64-unknown-linux-gnu/codex-linux-sandbox-aarch64-unknown-linux-gnu.zst" \
      -o "$BIN_DIR/codex-linux-sandbox-arm64"
 
-echo "Installed native dependencies into $BIN_DIR"
+if [[ "$INCLUDE_RUST" -eq 1 ]]; then
+  # x64 Linux
+  zstd -d "$ARTIFACTS_DIR/x86_64-unknown-linux-musl/codex-x86_64-unknown-linux-musl.zst" \
+      -o "$BIN_DIR/codex-x86_64-unknown-linux-musl"
+  # ARM64 Linux
+  zstd -d "$ARTIFACTS_DIR/aarch64-unknown-linux-gnu/codex-aarch64-unknown-linux-gnu.zst" \
+      -o "$BIN_DIR/codex-aarch64-unknown-linux-gnu"
+  # x64 macOS
+  zstd -d "$ARTIFACTS_DIR/x86_64-apple-darwin/codex-x86_64-apple-darwin.zst" \
+      -o "$BIN_DIR/codex-x86_64-apple-darwin"
+  # ARM64 macOS
+  zstd -d "$ARTIFACTS_DIR/aarch64-apple-darwin/codex-aarch64-apple-darwin.zst" \
+      -o "$BIN_DIR/codex-aarch64-apple-darwin"
+fi
 
+echo "Installed native dependencies into $BIN_DIR"