@lavilas/codex 1.3.55 → 1.3.61

package/bin/codex.js

@@ -2,69 +2,31 @@
 // Unified entry point for the Codex CLI.
 
 import { spawn } from "node:child_process";
-import { chmodSync, existsSync, readdirSync, statSync } from "fs";
+import { chmodSync, existsSync, readFileSync, readdirSync, statSync } from "fs";
 import { createRequire } from "node:module";
 import path from "path";
 import { fileURLToPath } from "url";
+import {
+  PLATFORM_PACKAGE_BY_TARGET,
+  detectPackageManager,
+  getCodexBinaryName,
+  resolveTargetTriple,
+  resolveRuntimeCacheRoot,
+  selectVendorInstallation,
+  updateCommandForPackageManager,
+} from "./platform-resolver.js";
 
 // __dirname equivalent in ESM
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+const packageDir = path.join(__dirname, "..");
 const require = createRequire(import.meta.url);
-
-const PLATFORM_PACKAGE_BY_TARGET = {
-  "x86_64-unknown-linux-musl": "@lavilas/codex-linux-x64",
-  "aarch64-unknown-linux-musl": "@lavilas/codex-linux-arm64",
-  "x86_64-apple-darwin": "@lavilas/codex-darwin-x64",
-  "aarch64-apple-darwin": "@lavilas/codex-darwin-arm64",
-  "x86_64-pc-windows-msvc": "@lavilas/codex-win32-x64",
-  "aarch64-pc-windows-msvc": "@lavilas/codex-win32-arm64",
-};
+const rootPackageJson = JSON.parse(
+  readFileSync(path.join(packageDir, "package.json"), "utf8"),
+);
 
 const { platform, arch } = process;
-
-let targetTriple = null;
-switch (platform) {
-  case "linux":
-  case "android":
-    switch (arch) {
-      case "x64":
-        targetTriple = "x86_64-unknown-linux-musl";
-        break;
-      case "arm64":
-        targetTriple = "aarch64-unknown-linux-musl";
-        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;
-  case "win32":
-    switch (arch) {
-      case "x64":
-        targetTriple = "x86_64-pc-windows-msvc";
-        break;
-      case "arm64":
-        targetTriple = "aarch64-pc-windows-msvc";
-        break;
-      default:
-        break;
-    }
-    break;
-  default:
-    break;
-}
+const targetTriple = resolveTargetTriple(platform, arch);
 
 if (!targetTriple) {
   throw new Error(`Unsupported platform: ${platform} (${arch})`);
@@ -75,47 +37,29 @@ if (!platformPackage) {
   throw new Error(`Unsupported target triple: ${targetTriple}`);
 }
 
-const codexBinaryName = process.platform === "win32" ? "codex.exe" : "codex";
-const localVendorRoot = path.join(__dirname, "..", "vendor");
-const localBinaryPath = path.join(
-  localVendorRoot,
-  targetTriple,
-  "codex",
-  codexBinaryName,
-);
+const codexBinaryName = getCodexBinaryName(process.platform);
+const localVendorRoot = path.join(packageDir, "vendor");
 
-let vendorRoot;
-try {
-  const packageJsonPath = require.resolve(`${platformPackage}/package.json`);
-  vendorRoot = path.join(path.dirname(packageJsonPath), "vendor");
-} catch {
-  if (existsSync(localBinaryPath)) {
-    vendorRoot = localVendorRoot;
-  } else {
-    const packageManager = detectPackageManager();
-    const updateCommand =
-      packageManager === "bun"
-        ? "bun install -g @lavilas/codex@latest"
-        : "npm install -g @lavilas/codex@latest";
-    throw new Error(
-      `Missing optional dependency ${platformPackage}. Reinstall Codex: ${updateCommand}`,
-    );
-  }
-}
+const selectedInstallation = selectVendorInstallation({
+  packageDir,
+  platformPackage,
+  targetTriple,
+  binaryName: codexBinaryName,
+  packageVersion: rootPackageJson.version ?? null,
+  runtimeCacheRoot: resolveRuntimeCacheRoot(),
+  localVendorRoot,
+  requireResolve: (specifier) => require.resolve(specifier),
+});
 
-if (!vendorRoot) {
-  const packageManager = detectPackageManager();
-  const updateCommand =
-    packageManager === "bun"
-      ? "bun install -g @lavilas/codex@latest"
-      : "npm install -g @lavilas/codex@latest";
+if (!selectedInstallation) {
+  const packageManager = detectPackageManager({ installDir: __dirname });
+  const updateCommand = updateCommandForPackageManager(packageManager);
   throw new Error(
     `Missing optional dependency ${platformPackage}. Reinstall Codex: ${updateCommand}`,
   );
 }
 
-const archRoot = path.join(vendorRoot, targetTriple);
-const binaryPath = path.join(archRoot, "codex", codexBinaryName);
+const binaryPath = selectedInstallation.binaryPath;
 
 // Use an asynchronous spawn instead of spawnSync so that Node is able to
 // respond to signals (e.g. Ctrl-C / SIGINT) while the native binary is
@@ -133,33 +77,8 @@ function getUpdatedPath(newDirs) {
   return updatedPath;
 }
 
-/**
- * Use heuristics to detect the package manager that was used to install Codex
- * in order to give the user a hint about how to update it.
- */
-function detectPackageManager() {
-  const userAgent = process.env.npm_config_user_agent || "";
-  if (/\bbun\//.test(userAgent)) {
-    return "bun";
-  }
-
-  const execPath = process.env.npm_execpath || "";
-  if (execPath.includes("bun")) {
-    return "bun";
-  }
-
-  if (
-    __dirname.includes(".bun/install/global") ||
-    __dirname.includes(".bun\\install\\global")
-  ) {
-    return "bun";
-  }
-
-  return userAgent ? "npm" : null;
-}
-
 const additionalDirs = [];
-const pathDir = path.join(archRoot, "path");
+const pathDir = selectedInstallation.pathDir;
 if (existsSync(pathDir)) {
   additionalDirs.push(pathDir);
 }
@@ -167,7 +86,7 @@ const updatedPath = getUpdatedPath(additionalDirs);
 
 const env = { ...process.env, PATH: updatedPath };
 const packageManagerEnvVar =
-  detectPackageManager() === "bun"
+  detectPackageManager({ installDir: __dirname }) === "bun"
     ? "CODEX_MANAGED_BY_BUN"
     : "CODEX_MANAGED_BY_NPM";
 env[packageManagerEnvVar] = "1";

package/bin/platform-resolver.js

@@ -0,0 +1,680 @@
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { createHash } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+
+export const PLATFORM_PACKAGE_BY_TARGET = {
+  "x86_64-unknown-linux-musl": "@lavilas/codex-linux-x64",
+  "aarch64-unknown-linux-musl": "@lavilas/codex-linux-arm64",
+  "x86_64-apple-darwin": "@lavilas/codex-darwin-x64",
+  "aarch64-apple-darwin": "@lavilas/codex-darwin-arm64",
+  "x86_64-pc-windows-msvc": "@lavilas/codex-win32-x64",
+  "aarch64-pc-windows-msvc": "@lavilas/codex-win32-arm64",
+};
+
+export function resolveTargetTriple(
+  platformName = process.platform,
+  archName = process.arch,
+) {
+  switch (platformName) {
+    case "linux":
+    case "android":
+      switch (archName) {
+        case "x64":
+          return "x86_64-unknown-linux-musl";
+        case "arm64":
+          return "aarch64-unknown-linux-musl";
+        default:
+          return null;
+      }
+    case "darwin":
+      switch (archName) {
+        case "x64":
+          return "x86_64-apple-darwin";
+        case "arm64":
+          return "aarch64-apple-darwin";
+        default:
+          return null;
+      }
+    case "win32":
+      switch (archName) {
+        case "x64":
+          return "x86_64-pc-windows-msvc";
+        case "arm64":
+          return "aarch64-pc-windows-msvc";
+        default:
+          return null;
+      }
+    default:
+      return null;
+  }
+}
+
+export function getCodexBinaryName(platformName = process.platform) {
+  return platformName === "win32" ? "codex.exe" : "codex";
+}
+
+export function detectPackageManager(options = {}) {
+  const userAgent = options.userAgent ?? process.env.npm_config_user_agent ?? "";
+  if (/\bbun\//.test(userAgent)) {
+    return "bun";
+  }
+
+  const execPath = options.execPath ?? process.env.npm_execpath ?? "";
+  if (execPath.includes("bun")) {
+    return "bun";
+  }
+
+  const installDir = options.installDir ?? "";
+  if (
+    installDir.includes(".bun/install/global") ||
+    installDir.includes(".bun\\install\\global")
+  ) {
+    return "bun";
+  }
+
+  return userAgent ? "npm" : null;
+}
+
+export function updateCommandForPackageManager(packageManager) {
+  return packageManager === "bun"
+    ? "bun install -g @lavilas/codex@latest"
+    : "npm install -g @lavilas/codex@latest";
+}
+
+function packageNameSegments(packageName) {
+  return packageName.split("/");
+}
+
+function packageInstallDir(packageDir, platformPackage) {
+  return path.join(packageDir, "node_modules", ...packageNameSegments(platformPackage));
+}
+
+function packageCacheBaseDir(runtimeCacheRoot, platformPackage) {
+  if (!runtimeCacheRoot) {
+    return null;
+  }
+  return path.join(runtimeCacheRoot, ...packageNameSegments(platformPackage));
+}
+
+function packageCacheDir(
+  runtimeCacheRoot,
+  platformPackage,
+  packageVersion,
+  manifestDigest = null,
+) {
+  if (!runtimeCacheRoot || !packageVersion) {
+    return null;
+  }
+  const cacheBaseDir = packageCacheBaseDir(runtimeCacheRoot, platformPackage);
+  if (!cacheBaseDir) {
+    return null;
+  }
+  const cacheKey = manifestDigest
+    ? `${packageVersion}-${manifestDigest.slice(0, 12)}`
+    : packageVersion;
+  return path.join(cacheBaseDir, cacheKey);
+}
+
+export function resolveRuntimeCacheRoot({
+  env = process.env,
+  homeDir = (() => {
+    try {
+      return os.homedir();
+    } catch {
+      return null;
+    }
+  })(),
+  platformName = process.platform,
+} = {}) {
+  const explicitCacheDir =
+    env.LAVILAS_CODEX_VENDOR_CACHE_DIR ?? env.CODEX_VENDOR_CACHE_DIR ?? null;
+  if (explicitCacheDir) {
+    return path.resolve(explicitCacheDir);
+  }
+
+  const codexHome =
+    env.CODEX_HOME ?? (homeDir ? path.join(homeDir, ".codex") : null);
+  if (codexHome) {
+    return path.join(codexHome, "runtime", "npm");
+  }
+
+  if (!homeDir) {
+    return null;
+  }
+
+  switch (platformName) {
+    case "win32": {
+      const localAppData = env.LOCALAPPDATA || path.join(homeDir, "AppData", "Local");
+      return path.join(localAppData, "Lavilas", "Codex", "runtime", "npm");
+    }
+    case "darwin":
+      return path.join(homeDir, "Library", "Caches", "Lavilas", "Codex", "runtime", "npm");
+    default: {
+      const xdgCacheHome = env.XDG_CACHE_HOME || path.join(homeDir, ".cache");
+      return path.join(xdgCacheHome, "lavilas-codex", "runtime", "npm");
+    }
+  }
+}
+
+function readJsonFile(filePath) {
+  try {
+    if (!existsSync(filePath)) {
+      return null;
+    }
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function vendorManifestFor(vendorRoot) {
+  return readJsonFile(path.join(vendorRoot, "manifest.json"));
+}
+
+function vendorManifestDigest(vendorRoot) {
+  try {
+    const manifestContents = readFileSync(path.join(vendorRoot, "manifest.json"));
+    return createHash("sha256").update(manifestContents).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+function readyMarkerPathFor(vendorRoot) {
+  return path.join(path.dirname(vendorRoot), ".ready.json");
+}
+
+function readyMarkerFor(vendorRoot) {
+  return readJsonFile(readyMarkerPathFor(vendorRoot));
+}
+
+function validateVendorManifest(manifest, vendorRoot) {
+  if (!manifest || typeof manifest !== "object") {
+    return { valid: false, reason: "missing manifest.json" };
+  }
+
+  const files = manifest.files;
+  if (!files || typeof files !== "object") {
+    return { valid: false, reason: "invalid manifest.json files map" };
+  }
+
+  for (const [relativePath, metadata] of Object.entries(files)) {
+    const candidatePath = path.join(vendorRoot, relativePath);
+    if (!existsSync(candidatePath)) {
+      return { valid: false, reason: `missing ${relativePath}` };
+    }
+
+    let candidateStat;
+    try {
+      candidateStat = statSync(candidatePath);
+    } catch {
+      return { valid: false, reason: `unable to stat ${relativePath}` };
+    }
+
+    if (!candidateStat.isFile() || candidateStat.size <= 0) {
+      return { valid: false, reason: `invalid ${relativePath}` };
+    }
+
+    if (
+      metadata &&
+      typeof metadata === "object" &&
+      typeof metadata.size === "number" &&
+      metadata.size !== candidateStat.size
+    ) {
+      return { valid: false, reason: `size mismatch for ${relativePath}` };
+    }
+  }
+
+  return { valid: true };
+}
+
+function validateVendorRoot(
+  candidate,
+  targetTriple,
+  binaryName,
+  { requireReadyMarker = false } = {},
+) {
+  const manifest = vendorManifestFor(candidate.vendorRoot);
+  const manifestValidation = validateVendorManifest(manifest, candidate.vendorRoot);
+  if (!manifestValidation.valid) {
+    return manifestValidation;
+  }
+
+  if (requireReadyMarker) {
+    const readyMarker = readyMarkerFor(candidate.vendorRoot);
+    if (!readyMarker || typeof readyMarker !== "object") {
+      return { valid: false, reason: "missing .ready.json" };
+    }
+    if (
+      candidate.cacheKey &&
+      typeof readyMarker.cacheKey === "string" &&
+      readyMarker.cacheKey !== candidate.cacheKey
+    ) {
+      return { valid: false, reason: "runtime cache marker mismatch" };
+    }
+  }
+
+  const binaryRelativePath = `${targetTriple}/codex/${binaryName}`;
+  const binaryPath = path.join(candidate.vendorRoot, binaryRelativePath);
+  if (!existsSync(binaryPath)) {
+    return { valid: false, reason: `missing ${binaryRelativePath}` };
+  }
+
+  let binaryStat;
+  try {
+    binaryStat = statSync(binaryPath);
+  } catch {
+    return { valid: false, reason: `unable to stat ${binaryRelativePath}` };
+  }
+  if (!binaryStat.isFile() || binaryStat.size <= 0) {
+    return { valid: false, reason: `invalid ${binaryRelativePath}` };
+  }
+
+  const expectedBinary = manifest?.files?.[binaryRelativePath];
+  if (
+    expectedBinary &&
+    typeof expectedBinary.size === "number" &&
+    expectedBinary.size !== binaryStat.size
+  ) {
+    return {
+      valid: false,
+      reason: `size mismatch for ${binaryRelativePath}`,
+    };
+  }
+
+  return {
+    valid: true,
+    binaryPath,
+    pathDir: path.join(candidate.vendorRoot, targetTriple, "path"),
+    vendorRoot: candidate.vendorRoot,
+    source: candidate.source,
+  };
+}
+
+function pushCandidate(candidates, seen, vendorRoot, source) {
+  if (!existsSync(vendorRoot)) {
+    return;
+  }
+  const resolvedRoot = path.resolve(vendorRoot);
+  if (seen.has(resolvedRoot)) {
+    return;
+  }
+  seen.add(resolvedRoot);
+  candidates.push({ vendorRoot: resolvedRoot, source });
+}
+
+function copyDirectoryRecursive(sourceDir, destinationDir) {
+  mkdirSync(destinationDir, { recursive: true });
+
+  for (const entry of readdirSync(sourceDir, { withFileTypes: true })) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const destinationPath = path.join(destinationDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirectoryRecursive(sourcePath, destinationPath);
+      continue;
+    }
+
+    if (entry.isSymbolicLink()) {
+      const resolvedPath = realpathSync(sourcePath);
+      const resolvedStat = statSync(resolvedPath);
+      if (resolvedStat.isDirectory()) {
+        copyDirectoryRecursive(resolvedPath, destinationPath);
+      } else {
+        copyFileSync(resolvedPath, destinationPath);
+        chmodSync(destinationPath, resolvedStat.mode);
+      }
+      continue;
+    }
+
+    const sourceStat = lstatSync(sourcePath);
+    if (sourceStat.isDirectory()) {
+      copyDirectoryRecursive(sourcePath, destinationPath);
+      continue;
+    }
+
+    copyFileSync(sourcePath, destinationPath);
+    chmodSync(destinationPath, sourceStat.mode);
+  }
+}
+
+function runtimeCacheCandidate({
+  runtimeCacheRoot,
+  platformPackage,
+  packageVersion,
+  manifestDigest = null,
+  source = "runtime-cache",
+}) {
+  const cacheDir = packageCacheDir(
+    runtimeCacheRoot,
+    platformPackage,
+    packageVersion,
+    manifestDigest,
+  );
+  if (!cacheDir) {
+    return null;
+  }
+  return {
+    vendorRoot: path.join(cacheDir, "vendor"),
+    cacheKey: path.basename(cacheDir),
+    source,
+  };
+}
+
+function collectRuntimeCacheCandidates({
+  runtimeCacheRoot,
+  platformPackage,
+  packageVersion,
+}) {
+  const cacheBaseDir = packageCacheBaseDir(runtimeCacheRoot, platformPackage);
+  if (!cacheBaseDir || !packageVersion || !existsSync(cacheBaseDir)) {
+    return [];
+  }
+
+  const versionPrefix = `${packageVersion}-`;
+  return readdirSync(cacheBaseDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name.startsWith(versionPrefix))
+    .map((entry) => ({
+      vendorRoot: path.join(cacheBaseDir, entry.name, "vendor"),
+      cacheKey: entry.name,
+      source: "runtime-cache",
+    }));
+}
+
+function materializeRuntimeCache({
+  runtimeCacheRoot,
+  platformPackage,
+  packageVersion,
+  targetTriple,
+  binaryName,
+  sourceInstallation,
+}) {
+  const manifestDigest = vendorManifestDigest(sourceInstallation.vendorRoot);
+  const cacheDir = packageCacheDir(
+    runtimeCacheRoot,
+    platformPackage,
+    packageVersion,
+    manifestDigest,
+  );
+  if (!cacheDir || !manifestDigest) {
+    return null;
+  }
+
+  const cachedCandidate = runtimeCacheCandidate({
+    runtimeCacheRoot,
+    platformPackage,
+    packageVersion,
+    manifestDigest,
+    source: `runtime-cache:${sourceInstallation.source}`,
+  });
+  if (!cachedCandidate) {
+    return null;
+  }
+
+  const cachedInstallation = validateVendorRoot(
+    cachedCandidate,
+    targetTriple,
+    binaryName,
+    { requireReadyMarker: true },
+  );
+  if (cachedInstallation.valid) {
+    return cachedInstallation;
+  }
+
+  const cacheParentDir = path.dirname(cacheDir);
+  mkdirSync(cacheParentDir, { recursive: true });
+
+  const tempCacheDir = path.join(
+    cacheParentDir,
+    `.tmp-${packageVersion}-${process.pid}-${Date.now()}-${Math.random()
+      .toString(16)
+      .slice(2)}`,
+  );
+
+  try {
+    copyDirectoryRecursive(sourceInstallation.vendorRoot, path.join(tempCacheDir, "vendor"));
+
+    const stagedInstallation = validateVendorRoot(
+      {
+        vendorRoot: path.join(tempCacheDir, "vendor"),
+        cacheKey: path.basename(cacheDir),
+        source: `runtime-cache-staging:${sourceInstallation.source}`,
+      },
+      targetTriple,
+      binaryName,
+    );
+    if (!stagedInstallation.valid) {
+      return null;
+    }
+
+    const readyMarker = {
+      cacheKey: path.basename(cacheDir),
+      platformPackage,
+      packageVersion,
+      targetTriple,
+      manifestSha256: manifestDigest,
+      createdAt: new Date().toISOString(),
+    };
+    writeFileSync(
+      readyMarkerPathFor(path.join(tempCacheDir, "vendor")),
+      `${JSON.stringify(readyMarker, null, 2)}\n`,
+    );
+
+    try {
+      renameSync(tempCacheDir, cacheDir);
+    } catch {
+      const currentInstallation = validateVendorRoot(
+        cachedCandidate,
+        targetTriple,
+        binaryName,
+        { requireReadyMarker: true },
+      );
+      if (currentInstallation.valid) {
+        return currentInstallation;
+      }
+
+      const currentReadyMarker = readyMarkerFor(cachedCandidate.vendorRoot);
+      if (!currentReadyMarker && existsSync(cacheDir)) {
+        rmSync(cacheDir, { recursive: true, force: true });
+        renameSync(tempCacheDir, cacheDir);
+      } else {
+        return null;
+      }
+    }
+
+    const finalInstallation = validateVendorRoot(
+      cachedCandidate,
+      targetTriple,
+      binaryName,
+      { requireReadyMarker: true },
+    );
+    return finalInstallation.valid ? finalInstallation : null;
+  } catch {
+    return null;
+  } finally {
+    rmSync(tempCacheDir, { recursive: true, force: true });
+  }
+}
+
+export function collectVendorCandidates({
+  packageDir,
+  platformPackage,
+  localVendorRoot = path.join(packageDir, "vendor"),
+  requireResolve = null,
+}) {
+  const candidates = [];
+  const seen = new Set();
+
+  if (typeof requireResolve === "function") {
+    try {
+      const packageJsonPath = requireResolve(`${platformPackage}/package.json`);
+      pushCandidate(
+        candidates,
+        seen,
+        path.join(path.dirname(packageJsonPath), "vendor"),
+        "resolved-platform-package",
+      );
+    } catch {
+      // Ignore and continue with direct filesystem fallbacks.
+    }
+  }
+
+  pushCandidate(
+    candidates,
+    seen,
+    path.join(packageInstallDir(packageDir, platformPackage), "vendor"),
+    "nested-platform-package",
+  );
+
+  const scopeDir = path.resolve(packageDir, "..");
+  if (existsSync(scopeDir)) {
+    for (const entry of readdirSync(scopeDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || !entry.name.startsWith(".codex-")) {
+        continue;
+      }
+      pushCandidate(
+        candidates,
+        seen,
+        path.join(scopeDir, entry.name, "node_modules", ...packageNameSegments(platformPackage), "vendor"),
+        `staged-platform-package:${entry.name}`,
+      );
+    }
+  }
+
+  pushCandidate(candidates, seen, localVendorRoot, "local-vendor-root");
+
+  return candidates;
+}
+
+export function selectVendorInstallation({
+  packageDir,
+  platformPackage,
+  targetTriple,
+  binaryName,
+  packageVersion = null,
+  runtimeCacheRoot = null,
+  localVendorRoot = path.join(packageDir, "vendor"),
+  requireResolve = null,
+}) {
+  const candidates = collectVendorCandidates({
+    packageDir,
+    platformPackage,
+    localVendorRoot,
+    requireResolve,
+  });
+  for (const candidate of candidates) {
+    const result = validateVendorRoot(candidate, targetTriple, binaryName);
+    if (result.valid) {
+      return (
+        materializeRuntimeCache({
+          runtimeCacheRoot,
+          platformPackage,
+          packageVersion,
+          targetTriple,
+          binaryName,
+          sourceInstallation: result,
+        }) ?? result
+      );
+    }
+  }
+
+  for (const cachedCandidate of collectRuntimeCacheCandidates({
+    runtimeCacheRoot,
+    platformPackage,
+    packageVersion,
+  })) {
+    const cachedInstallation = validateVendorRoot(
+      cachedCandidate,
+      targetTriple,
+      binaryName,
+      { requireReadyMarker: true },
+    );
+    if (cachedInstallation.valid) {
+      return cachedInstallation;
+    }
+  }
+
+  return null;
+}
+
+export function buildPlatformPackageMetadata({
+  platformPackage,
+  version,
+  license = "Apache-2.0",
+  repository = null,
+  packageManager = null,
+}) {
+  const metadata = {
+    name: platformPackage,
+    version,
+    license,
+    files: ["vendor"],
+  };
+  if (repository) {
+    metadata.repository = repository;
+  }
+  if (packageManager) {
+    metadata.packageManager = packageManager;
+  }
+
+  if (platformPackage.includes("linux")) {
+    metadata.os = ["linux"];
+  } else if (platformPackage.includes("darwin")) {
+    metadata.os = ["darwin"];
+  } else if (platformPackage.includes("win32")) {
+    metadata.os = ["win32"];
+  }
+
+  if (platformPackage.endsWith("x64")) {
+    metadata.cpu = ["x64"];
+  } else if (platformPackage.endsWith("arm64")) {
+    metadata.cpu = ["arm64"];
+  }
+
+  metadata.engines = { node: ">=16" };
+  return metadata;
+}
+
+export function ensurePlatformPackageMetadata({
+  packageDir,
+  platformPackage,
+  version,
+  license = "Apache-2.0",
+  repository = null,
+  packageManager = null,
+}) {
+  const vendorRoot = path.join(packageDir, "vendor");
+  if (!existsSync(vendorRoot)) {
+    return null;
+  }
+
+  const packageJsonPath = path.join(packageDir, "package.json");
+  if (existsSync(packageJsonPath)) {
+    return packageJsonPath;
+  }
+
+  mkdirSync(packageDir, { recursive: true });
+  const metadata = buildPlatformPackageMetadata({
+    platformPackage,
+    version,
+    license,
+    repository,
+    packageManager,
+  });
+  writeFileSync(packageJsonPath, `${JSON.stringify(metadata, null, 2)}\n`);
+  return packageJsonPath;
+}

package/bin/postinstall.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  PLATFORM_PACKAGE_BY_TARGET,
+  detectPackageManager,
+  ensurePlatformPackageMetadata,
+  getCodexBinaryName,
+  resolveTargetTriple,
+  resolveRuntimeCacheRoot,
+  selectVendorInstallation,
+  updateCommandForPackageManager,
+} from "./platform-resolver.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageDir = path.join(__dirname, "..");
+const require = createRequire(import.meta.url);
+
+if (!packageDir.includes(`${path.sep}node_modules${path.sep}`)) {
+  process.exit(0);
+}
+
+const targetTriple = resolveTargetTriple();
+if (!targetTriple) {
+  process.exit(0);
+}
+
+const platformPackage = PLATFORM_PACKAGE_BY_TARGET[targetTriple];
+if (!platformPackage) {
+  process.exit(0);
+}
+
+const rootPackageJson = JSON.parse(
+  readFileSync(path.join(packageDir, "package.json"), "utf8"),
+);
+ensurePlatformPackageMetadata({
+  packageDir: path.join(packageDir, "node_modules", ...platformPackage.split("/")),
+  platformPackage,
+  version: rootPackageJson.optionalDependencies?.[platformPackage] ?? rootPackageJson.version,
+  license: rootPackageJson.license ?? "Apache-2.0",
+  repository: rootPackageJson.repository ?? null,
+  packageManager: rootPackageJson.packageManager ?? null,
+});
+
+const selectedInstallation = selectVendorInstallation({
+  packageDir,
+  platformPackage,
+  targetTriple,
+  binaryName: getCodexBinaryName(),
+  packageVersion: rootPackageJson.version ?? null,
+  runtimeCacheRoot: resolveRuntimeCacheRoot(),
+  requireResolve: (specifier) => require.resolve(specifier),
+});
+
+if (!selectedInstallation) {
+  const packageManager = detectPackageManager({ installDir: __dirname });
+  const updateCommand = updateCommandForPackageManager(packageManager);
+  console.error(
+    `[lavilas/codex] Failed to validate ${platformPackage}. Reinstall Codex: ${updateCommand}`,
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(selectedInstallation.binaryPath, ["--version"], {
+  stdio: "pipe",
+  encoding: "utf8",
+  timeout: 15000,
+});
+
+if (result.error) {
+  console.error(
+    `[lavilas/codex] Native binary validation failed: ${result.error.message}`,
+  );
+  process.exit(1);
+}
+
+if (result.signal) {
+  console.error(
+    `[lavilas/codex] Native binary exited with signal ${result.signal} during install validation.`,
+  );
+  process.exit(1);
+}
+
+if (result.status !== 0) {
+  const details = (result.stderr || result.stdout || "").trim();
+  if (details) {
+    console.error(details);
+  }
+  process.exit(result.status ?? 1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lavilas/codex",
-  "version": "1.3.55",
+  "version": "1.3.61",
   "license": "Apache-2.0",
   "bin": {
     "codex": "bin/codex.js",
@@ -12,6 +12,10 @@
   "engines": {
     "node": ">=16"
   },
+  "scripts": {
+    "postinstall": "node bin/postinstall.js",
+    "test:bin": "node --test bin/platform-resolver.test.js"
+  },
   "files": [
     "bin"
   ],
@@ -22,11 +26,11 @@
   },
   "packageManager": "pnpm@10.29.3+sha512.498e1fb4cca5aa06c1dcf2611e6fafc50972ffe7189998c409e90de74566444298ffe43e6cd2acdc775ba1aa7cc5e092a8b7054c811ba8c5770f84693d33d2dc",
   "optionalDependencies": {
-    "@lavilas/codex-linux-x64": "1.3.55",
-    "@lavilas/codex-linux-arm64": "1.3.55",
-    "@lavilas/codex-darwin-x64": "1.3.55",
-    "@lavilas/codex-darwin-arm64": "1.3.55",
-    "@lavilas/codex-win32-x64": "1.3.55",
-    "@lavilas/codex-win32-arm64": "1.3.55"
+    "@lavilas/codex-linux-x64": "1.3.61",
+    "@lavilas/codex-linux-arm64": "1.3.61",
+    "@lavilas/codex-darwin-x64": "1.3.61",
+    "@lavilas/codex-darwin-arm64": "1.3.61",
+    "@lavilas/codex-win32-x64": "1.3.61",
+    "@lavilas/codex-win32-arm64": "1.3.61"
   }
 }