feat: ultra polish package manager (#13573)

See the readme

codex-rs/package-manager/src/package.rs

@@ -0,0 +1,69 @@
+use crate::PackageManagerError;
+use crate::PackagePlatform;
+use crate::PackageReleaseArchive;
+use crate::archive::detect_single_package_root;
+use serde::de::DeserializeOwned;
+use std::path::Path;
+use std::path::PathBuf;
+use url::Url;
+
+/// Describes how a specific package is located, validated, and loaded.
+///
+/// Implementations should treat this trait as the package manager contract:
+///
+/// - [`Self::install_dir`] should resolve to a directory unique to the package version and
+///   platform so concurrent versions never overwrite each other.
+/// - [`Self::load_installed`] should fully validate whatever "installed" means for the package,
+///   because cache resolution trusts a successful load as a valid install.
+/// - The default [`Self::detect_extracted_root`] implementation expects the extracted archive to
+///   contain a `manifest.json` at the package root or a single top-level directory that does.
+pub trait ManagedPackage: Clone {
+    /// Error type surfaced by package-specific loading and validation.
+    type Error: From<PackageManagerError>;
+
+    /// The fully loaded package instance returned to callers.
+    type Installed: Clone;
+
+    /// The decoded release manifest fetched from the remote source.
+    type ReleaseManifest: DeserializeOwned;
+
+    /// Returns the default cache root relative to Codex home.
+    fn default_cache_root_relative(&self) -> &str;
+
+    /// Returns the requested package version.
+    fn version(&self) -> &str;
+
+    /// Returns the manifest URL for the requested version.
+    fn manifest_url(&self) -> Result<Url, PackageManagerError>;
+
+    /// Returns the archive download URL for a platform-specific manifest entry.
+    fn archive_url(&self, archive: &PackageReleaseArchive) -> Result<Url, PackageManagerError>;
+
+    /// Returns the version string stored in the fetched release manifest.
+    fn release_version<'a>(&self, manifest: &'a Self::ReleaseManifest) -> &'a str;
+
+    /// Selects the archive to download for the current platform.
+    fn platform_archive(
+        &self,
+        manifest: &Self::ReleaseManifest,
+        platform: PackagePlatform,
+    ) -> Result<PackageReleaseArchive, Self::Error>;
+
+    /// Returns the final install directory for the package version and platform.
+    fn install_dir(&self, cache_root: &Path, platform: PackagePlatform) -> PathBuf;
+
+    /// Returns the version string encoded in a fully loaded installed package.
+    fn installed_version<'a>(&self, package: &'a Self::Installed) -> &'a str;
+
+    /// Loads and validates an installed package from disk.
+    fn load_installed(
+        &self,
+        root_dir: PathBuf,
+        platform: PackagePlatform,
+    ) -> Result<Self::Installed, Self::Error>;
+
+    /// Resolves the extracted package root before the staged install is promoted.
+    fn detect_extracted_root(&self, extraction_root: &Path) -> Result<PathBuf, Self::Error> {
+        detect_single_package_root(extraction_root).map_err(Self::Error::from)
+    }
+}