build: add Codex package builder (#23513)

## Why

Codex CLI packaging is currently split across npm staging, standalone
installers, and release bundle creation, which makes it hard to define
and validate a single valid package directory. This adds the first
standalone package builder so later release paths can converge on the
same canonical layout.

## What changed

- Added `scripts/build_codex_package.py` as the stable executable
wrapper around `scripts/codex_package`.
- Added modules for CLI parsing, target metadata, grouped cargo builds,
package layout validation, and archive writing.
- The builder creates a package directory with `codex-package.json`,
`bin/`, `codex-resources/`, and `codex-path`, and can serialize it as
`.tar.gz`, `.tar.zst`, or `.zip`.
- Source-built artifacts are built by one grouped `cargo build`: `codex`
for all targets, `bwrap` for Linux, and the Windows sandbox helpers for
Windows. `rg` remains an input because it is vendored from upstream
rather than built from this repo.
- Added `scripts/codex_package/README.md` to document the package
layout, source-built artifacts, and cargo profile behavior.

## Verification

- Ran wrapper/module syntax compilation.
- Ran `scripts/build_codex_package.py --help` from `/private/tmp`.
- Ran fake-cargo package/archive builds for macOS, Linux, and Windows
target layouts, including an assertion that generated tar archives
contain no duplicate member names.


---
[//]: # (BEGIN SAPLING FOOTER)
Stack created with [Sapling](https://sapling-scm.com). Best reviewed
with [ReviewStack](https://reviewstack.dev/openai/codex/pull/23513).
* #23526
* __->__ #23513

Author: bolinfest

scripts/build_codex_package.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""Build a canonical Codex package directory and optional archive."""
+
+from pathlib import Path
+import sys
+
+
+# Some developer environments set PYTHONSAFEPATH=1, which prevents Python from
+# adding the script directory to sys.path. Add it explicitly so the local helper
+# package remains importable when this executable is launched from any cwd.
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from codex_package.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/codex_package/README.md

@@ -0,0 +1,39 @@
+# Codex package builder
+
+This package contains the implementation behind `scripts/build_codex_package.py`.
+The top-level script is the stable executable entry point; these modules keep the
+package-building logic split by responsibility.
+
+The builder creates a canonical Codex package directory:
+
+```text
+.
+├── codex-package.json
+├── bin
+│   └── codex[.exe]
+├── codex-resources
+│   ├── bwrap                             # Linux only
+│   ├── codex-command-runner.exe          # Windows only
+│   └── codex-windows-sandbox-setup.exe   # Windows only
+└── codex-path
+    └── rg[.exe]
+```
+
+The package directory is the primary artifact. Archive formats such as
+`.tar.gz`, `.tar.zst`, and `.zip` are serializations of that directory.
+
+## Source-built artifacts
+
+Artifacts built from this repository are always built by the package builder in
+one grouped `cargo build` command per package:
+
+- all targets: `codex`
+- Linux targets: `bwrap`
+- Windows targets: `codex-command-runner` and `codex-windows-sandbox-setup`
+
+The default cargo profile is `dev-small` because local iteration should favor
+fast, small builds. Release jobs should pass `--cargo-profile release`.
+
+`rg` is not built from this repository, so it remains an input. If `--rg-bin` is
+omitted, the builder looks in the existing `codex-cli/vendor/<target>/path/`
+location.

scripts/codex_package/__init__.py

@@ -0,0 +1 @@
+"""Helpers for building canonical Codex package archives."""

scripts/codex_package/archive.py

@@ -0,0 +1,87 @@
+"""Archive writers for canonical Codex package directories."""
+
+import shutil
+import subprocess
+import tarfile
+import tempfile
+import zipfile
+from pathlib import Path
+
+
+def write_archive(package_dir: Path, archive_path: Path, *, force: bool) -> None:
+    if is_relative_to(archive_path, package_dir):
+        raise RuntimeError(
+            f"Archive output must be outside the package directory: {archive_path}"
+        )
+
+    archive_path.parent.mkdir(parents=True, exist_ok=True)
+    if archive_path.exists():
+        if not force:
+            raise RuntimeError(f"Archive output already exists: {archive_path}")
+        archive_path.unlink()
+
+    archive_format = archive_format_for_path(archive_path)
+    if archive_format == "tar.gz":
+        write_tar_archive(package_dir, archive_path, mode="w:gz")
+    elif archive_format == "tar.zst":
+        write_tar_zst_archive(package_dir, archive_path)
+    elif archive_format == "zip":
+        write_zip_archive(package_dir, archive_path)
+    else:
+        raise AssertionError(f"unexpected archive format: {archive_format}")
+
+
+def is_relative_to(path: Path, parent: Path) -> bool:
+    try:
+        path.relative_to(parent)
+        return True
+    except ValueError:
+        return False
+
+
+def archive_format_for_path(path: Path) -> str:
+    suffixes = path.suffixes
+    if suffixes[-2:] == [".tar", ".gz"] or path.suffix == ".tgz":
+        return "tar.gz"
+    if suffixes[-2:] == [".tar", ".zst"]:
+        return "tar.zst"
+    if path.suffix == ".zip":
+        return "zip"
+    raise RuntimeError(
+        f"Unsupported archive suffix for {path}. Use .tar.gz, .tgz, .tar.zst, or .zip."
+    )
+
+
+def write_tar_archive(package_dir: Path, archive_path: Path, *, mode: str) -> None:
+    with tarfile.open(archive_path, mode) as archive:
+        for path in package_entries(package_dir):
+            archive.add(
+                path,
+                arcname=path.relative_to(package_dir),
+                recursive=False,
+            )
+
+
+def write_tar_zst_archive(package_dir: Path, archive_path: Path) -> None:
+    zstd = shutil.which("zstd")
+    if zstd is None:
+        raise RuntimeError("zstd is required to write .tar.zst archives.")
+
+    with tempfile.TemporaryDirectory(prefix="codex-package-archive-") as temp_dir_str:
+        tar_path = Path(temp_dir_str) / "package.tar"
+        write_tar_archive(package_dir, tar_path, mode="w")
+        subprocess.check_call([zstd, "-T0", "-19", "-f", str(tar_path), "-o", str(archive_path)])
+
+
+def write_zip_archive(package_dir: Path, archive_path: Path) -> None:
+    with zipfile.ZipFile(archive_path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+        for path in package_entries(package_dir):
+            relative_path = path.relative_to(package_dir)
+            if path.is_dir():
+                archive.write(path, f"{relative_path}/")
+            else:
+                archive.write(path, relative_path)
+
+
+def package_entries(package_dir: Path) -> list[Path]:
+    return sorted(package_dir.rglob("*"), key=lambda path: path.relative_to(package_dir).as_posix())

scripts/codex_package/cargo.py

@@ -0,0 +1,106 @@
+"""Cargo builds for source-built Codex package artifacts."""
+
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from .targets import REPO_ROOT
+from .targets import TargetSpec
+
+
+CODEX_RS_ROOT = REPO_ROOT / "codex-rs"
+
+
+@dataclass(frozen=True)
+class SourceBuildOutputs:
+    codex_bin: Path
+    bwrap_bin: Path | None
+    codex_command_runner_bin: Path | None
+    codex_windows_sandbox_setup_bin: Path | None
+
+
+def build_source_binaries(
+    spec: TargetSpec,
+    *,
+    cargo: str,
+    profile: str,
+) -> SourceBuildOutputs:
+    binaries = source_binaries_for_target(spec)
+    cmd = [
+        cargo,
+        "build",
+        "--target",
+        spec.target,
+        "--profile",
+        profile,
+    ]
+    for binary in binaries:
+        cmd.extend(["--bin", binary])
+
+    print("+", " ".join(cmd))
+    subprocess.run(cmd, cwd=CODEX_RS_ROOT, check=True)
+
+    output_dir = cargo_profile_output_dir(spec, profile)
+    outputs = SourceBuildOutputs(
+        codex_bin=output_dir / spec.codex_name,
+        bwrap_bin=output_dir / "bwrap" if spec.is_linux else None,
+        codex_command_runner_bin=(
+            output_dir / "codex-command-runner.exe" if spec.is_windows else None
+        ),
+        codex_windows_sandbox_setup_bin=(
+            output_dir / "codex-windows-sandbox-setup.exe" if spec.is_windows else None
+        ),
+    )
+    validate_source_outputs(outputs)
+    return outputs
+
+
+def source_binaries_for_target(spec: TargetSpec) -> list[str]:
+    binaries = ["codex"]
+    if spec.is_linux:
+        binaries.append("bwrap")
+    if spec.is_windows:
+        binaries.extend(
+            [
+                "codex-command-runner",
+                "codex-windows-sandbox-setup",
+            ]
+        )
+    return binaries
+
+
+def cargo_profile_output_dir(spec: TargetSpec, profile: str) -> Path:
+    target_dir = cargo_target_dir()
+    return target_dir / spec.target / cargo_profile_dirname(profile)
+
+
+def cargo_target_dir() -> Path:
+    target_dir = os.environ.get("CARGO_TARGET_DIR")
+    if target_dir is None:
+        return CODEX_RS_ROOT / "target"
+
+    path = Path(target_dir)
+    if path.is_absolute():
+        return path
+
+    return CODEX_RS_ROOT / path
+
+
+def cargo_profile_dirname(profile: str) -> str:
+    if profile == "dev":
+        return "debug"
+    if profile == "release":
+        return "release"
+    return profile
+
+
+def validate_source_outputs(outputs: SourceBuildOutputs) -> None:
+    for path in [
+        outputs.codex_bin,
+        outputs.bwrap_bin,
+        outputs.codex_command_runner_bin,
+        outputs.codex_windows_sandbox_setup_bin,
+    ]:
+        if path is not None and not path.is_file():
+            raise RuntimeError(f"cargo build did not produce expected binary: {path}")

scripts/codex_package/cli.py

@@ -0,0 +1,105 @@
+"""Command-line interface for building Codex package directories."""
+
+import argparse
+from pathlib import Path
+
+from .archive import write_archive
+from .cargo import build_source_binaries
+from .layout import build_package_dir
+from .layout import prepare_package_dir
+from .layout import validate_package_dir
+from .targets import TARGET_SPECS
+from .targets import PackageInputs
+from .targets import resolve_rg_bin
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Build a canonical Codex package directory and optional archive.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "--target",
+        required=True,
+        choices=sorted(TARGET_SPECS),
+        help="Rust target triple for the package.",
+    )
+    parser.add_argument(
+        "--version",
+        default="0.0.0-dev",
+        help="Codex version to record in codex-package.json.",
+    )
+    parser.add_argument(
+        "--variant",
+        default="codex",
+        help="Package variant to record in codex-package.json.",
+    )
+    parser.add_argument(
+        "--package-dir",
+        type=Path,
+        required=True,
+        help="Output directory to create as the package root.",
+    )
+    parser.add_argument(
+        "--archive-output",
+        type=Path,
+        help=(
+            "Optional archive output path. Supported suffixes: .tar.gz, .tgz, "
+            ".tar.zst, .zip."
+        ),
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Replace an existing package directory or archive output.",
+    )
+    parser.add_argument(
+        "--cargo",
+        default="cargo",
+        help="Cargo executable to use for source-built package artifacts.",
+    )
+    parser.add_argument(
+        "--cargo-profile",
+        default="dev-small",
+        help=(
+            "Cargo profile for source-built package artifacts. Use release for "
+            "release packages."
+        ),
+    )
+    parser.add_argument(
+        "--rg-bin",
+        type=Path,
+        help="Path to the ripgrep executable to place in codex-path/.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    spec = TARGET_SPECS[args.target]
+    package_dir = args.package_dir.resolve()
+
+    source_outputs = build_source_binaries(
+        spec,
+        cargo=args.cargo,
+        profile=args.cargo_profile,
+    )
+    inputs = PackageInputs(
+        codex_bin=source_outputs.codex_bin,
+        rg_bin=resolve_rg_bin(spec, args.rg_bin),
+        bwrap_bin=source_outputs.bwrap_bin,
+        codex_command_runner_bin=source_outputs.codex_command_runner_bin,
+        codex_windows_sandbox_setup_bin=source_outputs.codex_windows_sandbox_setup_bin,
+    )
+    prepare_package_dir(package_dir, force=args.force)
+    build_package_dir(package_dir, args.version, args.variant, spec, inputs)
+    validate_package_dir(package_dir, spec)
+
+    archive_output = args.archive_output
+    if archive_output is not None:
+        archive_path = archive_output.resolve()
+        write_archive(package_dir, archive_path, force=args.force)
+        print(f"Built Codex package archive at {archive_path}")
+
+    print(f"Built Codex package directory at {package_dir}")
+    return 0