@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
902 lines (838 loc) • 41.2 kB
JavaScript
import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
import { basename, dirname, isAbsolute, join, parse, relative, resolve, win32 } from "node:path";
import { pnpmInvocationForPath } from "./pnpm-invocation.mjs";
import { pnpmPackageUsesGlobalStoreLinks, verifyPnpmInstallTree } from "./transactional-install.mjs";
export const PNPM_BUILD_APPROVAL = "--allow-build=bun";
/**
* pnpm majors whose global virtual-store install and `store path --dir=<pnpm home>` were checked to
* select the same store (11.20.0, 12.16.1). Another major refuses rather than assumes the same rules.
*/
const VERIFIED_GLOBAL_STORE_MAJORS = new Set([11, 12]);
/** Characters cmd.exe re-parses after quoting (same set as the npm cache preflight). */
const WINDOWS_CMD_METACHARACTERS = /["%!^&|<>]/;
/**
* On Windows pnpm.cmd re-parses its arguments in cmd.exe after quoting, so a global-store owner whose
* pnpm home, global directory or global bin directory carries one of these characters is refused
* before any owner-pinned pnpm command receives them (the npm cache preflight refuses the same set).
*/
function windowsCmdPathRefusal(owner, env, platform) {
if (platform !== "win32") return null;
const paths = [owner?.homeAnchor ?? pnpmHomeAnchor(env, platform), owner?.globalDir, owner?.globalBinDir];
return paths.some(path => WINDOWS_CMD_METACHARACTERS.test(String(path ?? "")))
? { ok: false, reason: "pnpm path contains a character cmd.exe cannot pass safely" } : null;
}
function outputText(value) {
if (typeof value === "string") return value;
if (value instanceof Uint8Array) return new TextDecoder().decode(value);
return "";
}
function pathKey(value, platform = process.platform) {
const raw = String(value).replaceAll("\\", "/");
const normalise = path => {
const result = path.replaceAll("\\", "/");
return platform === "win32" ? result.toLowerCase() : result;
};
try {
return normalise(realpathSync.native(raw));
} catch {
return normalise(resolve(raw));
}
}
function lexicalPathKey(value, platform = process.platform) {
const result = resolve(String(value).replaceAll("\\", "/")).replaceAll("\\", "/");
return platform === "win32" ? result.toLowerCase() : result;
}
function samePath(left, right, platform = process.platform) {
return pathKey(left, platform) === pathKey(right, platform)
|| lexicalPathKey(left, platform) === lexicalPathKey(right, platform);
}
function singleAbsoluteCommandPath(runPnpm, commandPath, args, platform = process.platform) {
let result;
try {
result = runPnpm(commandPath, args, true);
} catch {
return null;
}
if (result?.status !== 0) return null;
const lines = outputText(result.stdout).split(/\r?\n/).map(line => line.trim()).filter(Boolean);
if (lines.length !== 1 || /^(?:undefined|null)$/i.test(lines[0])) return null;
return isAbsolutePath(lines[0], platform) ? lines[0] : null;
}
function configPathValue(runPnpm, commandPath, key, platform = process.platform) {
return singleAbsoluteCommandPath(runPnpm, commandPath, ["config", "get", key], platform);
}
function absoluteConfigPath(value, platform = process.platform) {
return typeof value === "string" && isAbsolutePath(value, platform) ? value : null;
}
function isAbsolutePath(value, platform = process.platform) {
if (typeof value !== "string") return false;
return isAbsolute(value) || (
platform === "win32"
&& /^(?:[A-Za-z]:[\\/]|\\\\|\/)/.test(String(value))
);
}
function pathDirname(value, platform = process.platform) {
return platform === "win32" ? win32.dirname(String(value)) : dirname(value);
}
function pathBasename(value, platform = process.platform) {
return platform === "win32" ? win32.basename(String(value)) : basename(value);
}
/** Normalize pnpm list/root output to the versioned global group, not its node_modules root. */
function normaliseGlobalRoot(value, platform = process.platform) {
if (!isAbsolutePath(value, platform)) return null;
const trimmed = String(value).replace(/[\\/]+$/, "");
return pathBasename(trimmed, platform).toLowerCase() === "node_modules"
? pathDirname(trimmed, platform)
: trimmed;
}
/** pnpm's --global-dir is the base; pnpm appends the major-version group below it. */
function globalDirFromRoot(globalRoot, platform = process.platform) {
const separator = platform === "win32" ? /[\\/]/ : /\//;
const match = String(globalRoot).match(new RegExp(`^(.*)${separator.source}(?:v)?\\d+$`, "i"));
return match?.[1] || globalRoot;
}
function globalRootMatchesDir(globalRoot, globalDir, platform = process.platform) {
return samePath(globalRoot, globalDir, platform)
|| samePath(pathDirname(globalRoot, platform), globalDir, platform);
}
/** Resolve manager-owned global paths, including pnpm defaults that config get leaves undefined. */
function resolveGlobalPaths(commandPath, runPnpm, listedRoot, platform = process.platform) {
const listedGlobalRoot = normaliseGlobalRoot(listedRoot, platform);
const commandGlobalRoot = normaliseGlobalRoot(
singleAbsoluteCommandPath(runPnpm, commandPath, ["root", "-g"], platform),
platform,
);
if (listedGlobalRoot && commandGlobalRoot && !samePath(listedGlobalRoot, commandGlobalRoot, platform)) {
return null;
}
const globalRoot = commandGlobalRoot ?? listedGlobalRoot;
if (!globalRoot) return null;
const configuredGlobalDir = absoluteConfigPath(configPathValue(runPnpm, commandPath, "global-dir", platform), platform);
const globalDir = configuredGlobalDir ?? globalDirFromRoot(globalRoot, platform);
const configuredGlobalBinDir = absoluteConfigPath(configPathValue(runPnpm, commandPath, "global-bin-dir", platform), platform);
const globalBinDir = configuredGlobalBinDir
?? absoluteConfigPath(singleAbsoluteCommandPath(runPnpm, commandPath, ["bin", "-g"], platform), platform);
if (!globalDir || !globalBinDir || !globalRootMatchesDir(globalRoot, globalDir, platform)) return null;
return { globalDir, globalRoot, globalBinDir };
}
function packageEntryFromRoot(root, packageName) {
const maps = [root?.dependencies, root?.devDependencies, root?.optionalDependencies];
for (const dependencies of maps) {
if (!dependencies || typeof dependencies !== "object") continue;
const direct = dependencies[packageName];
if (direct && typeof direct === "object") return direct;
}
return null;
}
function inspectListOutput(stdout, packageName) {
let roots;
try {
roots = JSON.parse(outputText(stdout));
} catch {
return null;
}
if (!Array.isArray(roots)) return null;
for (const root of roots) {
const entry = packageEntryFromRoot(root, packageName);
if (entry) return { root, entry };
}
return null;
}
function ownerGlobalArgs(args, owner) {
const input = [...args];
if (!owner) return input;
const command = input[0];
if (!["add", "install", "update", "list", "remove", "uninstall"].includes(command)) return input;
const rest = [];
for (let index = 1; index < input.length; index += 1) {
const arg = input[index];
// The owner is authoritative. Remove an accidentally inherited/supplied value rather
// than relying on duplicate pnpm flags having stable precedence across pnpm 10/11.
if (arg === "--global-dir" || arg.startsWith("--global-dir=")) {
if (arg === "--global-dir") index += 1;
continue;
}
if (arg === "--config.global-bin-dir" || arg.startsWith("--config.global-bin-dir=")) {
if (arg === "--config.global-bin-dir") index += 1;
continue;
}
if (owner.storePath && (arg === "--store-dir" || arg.startsWith("--store-dir=")
|| arg === "--config.store-dir" || arg.startsWith("--config.store-dir="))) {
if (arg === "--store-dir" || arg === "--config.store-dir") index += 1;
continue;
}
rest.push(arg);
}
return [
command,
`--global-dir=${owner.globalDir}`,
`--config.global-bin-dir=${owner.globalBinDir}`,
...(["add", "install", "update", "remove", "uninstall"].includes(command) && owner.storePath ? [`--store-dir=${owner.storePath}`] : []),
...rest,
];
}
/** Add the selected pnpm global group and bin directory to a command's config. */
export function pnpmGlobalCommandArgs(args, owner) {
return ownerGlobalArgs(args, owner);
}
/**
* Add the owning global bin directory to PATH for commands such as pnpm's bin
* validation. Do not replace PATH: registry auth and the selected pnpm executable
* can depend on the rest of the inherited environment.
*/
export function pnpmOwnerEnvironment(owner, env = process.env, platform = process.platform) {
const key = platform === "win32" && env.Path !== undefined && env.PATH === undefined ? "Path" : "PATH";
const delimiter = platform === "win32" ? ";" : ":";
const existing = env[key] ?? env.PATH ?? env.Path ?? "";
const entries = String(existing).split(delimiter).filter(Boolean);
if (!entries.some(entry => samePath(entry, owner.globalBinDir, platform))) entries.unshift(owner.globalBinDir);
return { ...env, [key]: entries.join(delimiter) };
}
/** Build an invocation for the already-selected pnpm executable and global group. */
export function pnpmOwnerInvocation(owner, args, platform = process.platform, env = process.env) {
const ownerEnv = pnpmOwnerEnvironment(owner, env, platform);
const invocation = pnpmInvocationForPath(
owner.commandPath,
ownerGlobalArgs(args, owner),
platform,
ownerEnv,
);
return invocation ? { ...invocation, env: ownerEnv } : null;
}
function shimNames(platform) {
return platform === "win32"
? ["ocx.cmd", "ocx.ps1", "opencodex.cmd", "opencodex.ps1"]
: ["ocx", "opencodex"];
}
function targetVariants(packageDir, globalBinDir, platform) {
const packageCandidates = [packageDir];
try { packageCandidates.push(realpathSync(packageDir)); } catch { /* keep lexical path */ }
const binCandidates = [globalBinDir];
try { binCandidates.push(realpathSync(globalBinDir)); } catch { /* keep lexical path */ }
const launcherCandidates = packageCandidates.map(candidate => join(candidate, "bin", "ocx.mjs"));
const relativeCandidates = binCandidates.flatMap(bin => launcherCandidates.map(candidate => relative(bin, candidate)));
return [...new Set([...launcherCandidates, ...relativeCandidates].map(value => {
const normalised = String(value).replaceAll("\\", "/").replace(/^\.\//, "");
return platform === "win32" ? normalised.toLowerCase() : normalised;
}))].filter(Boolean);
}
function shimPointsToPackage(shimPath, packageDir, globalBinDir, platform) {
try {
if (samePath(shimPath, join(packageDir, "bin", "ocx.mjs"), platform)) return true;
} catch { /* fall through to text inspection */ }
let text;
try {
text = readFileSync(shimPath, "utf8").replaceAll("\\", "/");
if (platform === "win32") text = text.toLowerCase();
} catch {
return false;
}
// A comment containing the new path is not a launcher. Generated cmd/PowerShell
// shims are simple enough that the target appears on an executable line; discard
// shebang/hash and REM lines before matching so a stale or hand-edited shim cannot
// pass verification by mentioning the right package in a comment.
const executableText = text.split(/\r?\n/).filter(line => {
const trimmed = line.trim();
return !trimmed.startsWith("#") && !/^rem(?:\s|$)/i.test(trimmed);
}).join("\n");
const expectedLauncher = join(packageDir, "bin", "ocx.mjs");
if (shimTargetPaths(shimPath, executableText, platform).some(target => samePath(target, expectedLauncher, platform))) {
return true;
}
return targetVariants(packageDir, globalBinDir, platform).some(target => executableText.includes(target));
}
function shimIsRunnable(shimPath, platform) {
if (platform === "win32") return true;
try {
return (statSync(shimPath).mode & 0o111) !== 0;
} catch {
return false;
}
}
function shimTargetPaths(shimPath, text, platform) {
const targets = [];
const launcherPattern = /((?:\$basedir(?:_win)?|\$PSScriptRoot|%~dp0|[A-Za-z]:[\\/]|\/|\.\.?[\\/])[^"'`\r\n]*[\\/]bin[\\/]ocx\.mjs)/gi;
const shimDir = pathDirname(shimPath, platform);
for (const match of text.matchAll(launcherPattern)) {
let target = match[1];
target = target.replace(/\$basedir_win|\$basedir|\$PSScriptRoot|%~dp0/gi, shimDir);
target = target.replaceAll("\\", "/");
targets.push(isAbsolutePath(target, platform)
? target
: platform === "win32" ? win32.resolve(shimDir, target) : resolve(shimDir, target));
}
return targets;
}
/**
* Verify both generated command names and all launcher forms pnpm supports for
* the current platform. A package list/tree check is not enough: a stale shim
* can still execute the old global group after pnpm changes the active link.
*/
export function verifyPnpmGlobalShims(
packageDir,
globalBinDir,
platform = process.platform,
exists = existsSync,
) {
if (!isAbsolutePath(globalBinDir, platform)) {
return { ok: false, reason: "pnpm global bin directory is not absolute" };
}
const missing = [];
for (const name of shimNames(platform)) {
const path = join(globalBinDir, name);
if (
!exists(path)
|| !shimIsRunnable(path, platform)
|| !shimPointsToPackage(path, packageDir, globalBinDir, platform)
) missing.push(name);
}
return missing.length === 0
? { ok: true }
: { ok: false, reason: `pnpm generated shim verification failed (${missing.join(", ")})` };
}
function commandLines(result) {
return outputText(result?.stdout).split(/\r?\n/).map(line => line.trim()).filter(Boolean);
}
/**
* The directory pnpm loads its global configuration from (pnpm home): PNPM_HOME, then
* XDG_DATA_HOME/pnpm, then the platform default. It is read from the environment the pnpm
* commands receive, so the anchor and the commands agree.
*/
export function pnpmHomeAnchor(env = process.env, platform = process.platform) {
const value = key => typeof env?.[key] === "string" && env[key].trim() ? env[key] : null;
const joinPath = platform === "win32" ? win32.join : join;
let anchor = null;
if (value("PNPM_HOME")) anchor = value("PNPM_HOME");
else if (value("XDG_DATA_HOME")) anchor = joinPath(value("XDG_DATA_HOME"), "pnpm");
else if (platform === "win32") anchor = value("LOCALAPPDATA") ? win32.join(value("LOCALAPPDATA"), "pnpm") : null;
else if (value("HOME")) {
anchor = platform === "darwin" ? join(value("HOME"), "Library", "pnpm") : join(value("HOME"), ".local", "share", "pnpm");
}
// A control character could split a cmd.exe command line on Windows; such a home is never trusted.
return anchor && isAbsolutePath(anchor, platform) && !/[\u0000-\u001f\u007f]/.test(anchor) ? anchor : null;
}
/**
* Classify a spelling used as a confinement root (pnpm home, store path, global group). It is trusted
* only when it is already canonical: no "." or ".." segment (path.resolve would delete them without
* visiting the links they cross), no link or junction component, and realpath returns the same path.
* Case is folded for the last comparison only; a case-only symlink is caught by the component walk.
* Returns "link", "noncanonical" or "ok"; throws when the path is missing or not a directory.
*/
function spellingTrust(path) {
const raw = String(path);
const { root } = parse(raw);
const parts = raw.slice(root.length).split(/[\\/]+/).filter(Boolean);
if (!root || parts.some(part => part === "." || part === "..")) return "noncanonical";
let current = root;
for (const part of parts) {
current = join(current, part);
if (lstatSync(current).isSymbolicLink()) return "link";
}
if (!statSync(raw).isDirectory()) throw new Error("not a directory");
const fold = value => resolve(value).replaceAll("\\", "/").replace(/\/+$/, "").toLowerCase();
return fold(realpathSync.native(raw)) === fold(raw) ? "ok" : "noncanonical";
}
/** Map a spelling's trust to the refusal reason for the named root, or null when trusted. */
function spellingRefusal(path, label) {
const trust = spellingTrust(path);
if (trust === "link") return label + " has a symbolic link component";
if (trust === "noncanonical") return label + " is not a canonical path";
return null;
}
/** Appended to a store-proof refusal for an install whose path looks like a pnpm global store. */
const STORE_PROOF_HINT = "; this install's path looks like a pnpm global store (a store links directory or pnpm store markers), "
+ "so the updater accepts it only when pnpm 11 or 12 names that store. Update with pnpm itself: "
+ "pnpm add -g @bitkyc08/opencodex@latest";
/** Filesystem identity of a directory (device and inode), or null when it is not a readable directory. */
function directoryIdentity(path) {
try {
const stat = statSync(path);
return stat.isDirectory() ? `${stat.dev}:${stat.ino}` : null;
} catch { return null; }
}
/**
* A store owner's store and global group are pinned by filesystem identity for one update transaction, so a
* directory replaced at the same canonical path between the proof and a pnpm mutation (install or rollback)
* stops the transaction instead of receiving the mutation.
*/
function pinStoreOwnerIdentity(owner) {
const group = directoryIdentity(owner.globalRoot), store = directoryIdentity(owner.store);
return {
refusal() {
if (!group || directoryIdentity(owner.globalRoot) !== group) return "pnpm global group was replaced or could not be read";
if (!store || directoryIdentity(owner.store) !== store) return "pnpm configured store was replaced or could not be read";
return null;
},
};
}
/** Store-proof failures are configuration facts, not package-tree failures. */
function isStoreProofFailure(reason) {
return typeof reason === "string" && (reason.startsWith("pnpm configured store")
|| reason.startsWith("pnpm virtual-store") || reason.startsWith("pnpm store path")
|| reason.startsWith("pnpm home") || reason.startsWith("pnpm global-store behavior")
// A global group that lost its canonical spelling is a configuration fact too: no rollback through it.
|| reason.startsWith("pnpm global group"));
}
/**
* Ask the selected pnpm which store it uses for its global configuration. The answer counts only
* when the pnpm version is one whose global-store behavior was checked, the anchor is a real
* directory with no symbolic link component, and pnpm prints exactly one absolute versioned path.
* The lexical path and its canonical target are pinned separately and both must stay unchanged.
*/
function readPnpmStore(runPnpm, owner, platform, env = process.env) {
const unsafe = windowsCmdPathRefusal(owner, env, platform);
if (unsafe) return unsafe;
let pnpmVersion;
try {
const result = runPnpm(["--version"], true);
const lines = commandLines(result);
if (result?.status === 0 && lines.length === 1) pnpmVersion = lines[0];
} catch { /* refused below */ }
const major = /^(\d+)\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]*)?$/.exec(pnpmVersion ?? "")?.[1];
if (!major || !VERIFIED_GLOBAL_STORE_MAJORS.has(Number(major))) {
return { ok: false, reason: "pnpm global-store behavior is not verified for this pnpm version" };
}
const homeAnchor = owner?.homeAnchor ?? pnpmHomeAnchor(env, platform);
if (!homeAnchor) return { ok: false, reason: "pnpm home could not be determined" };
try {
const refusal = spellingRefusal(homeAnchor, "pnpm home");
if (refusal) return { ok: false, reason: refusal };
} catch {
return { ok: false, reason: "pnpm home could not be resolved" };
}
let storePath;
try {
const probe = runPnpm(["store", "path", `--dir=${homeAnchor}`], true);
const lines = commandLines(probe);
if (probe?.status === 0 && lines.length === 1 && isAbsolutePath(lines[0], platform)
&& /^v\d+$/.test(pathBasename(lines[0], platform))) storePath = lines[0];
} catch { /* refused below */ }
if (!storePath) return { ok: false, reason: "pnpm store path is not one absolute versioned path" };
if (platform === "win32" && WINDOWS_CMD_METACHARACTERS.test(storePath)) {
return { ok: false, reason: "pnpm path contains a character cmd.exe cannot pass safely" };
}
// A link inside the store spelling would widen the root every later hop is confined to.
try {
const refusal = spellingRefusal(storePath, "pnpm store path");
if (refusal) return { ok: false, reason: refusal };
} catch {
return { ok: false, reason: "pnpm store path could not be resolved" };
}
let store;
try {
store = realpathSync.native(storePath);
if (!statSync(store).isDirectory()) throw new Error();
} catch {
return { ok: false, reason: "pnpm store path could not be resolved" };
}
if (owner?.storePath && lexicalPathKey(storePath, platform) !== lexicalPathKey(owner.storePath, platform)) {
return { ok: false, reason: "pnpm configured store changed" };
}
if (owner?.store && lexicalPathKey(store, platform) !== lexicalPathKey(owner.store, platform)) {
return { ok: false, reason: "pnpm configured store changed" };
}
const virtualStoreDirs = [];
for (const key of ["virtual-store-dir", "global-virtual-store-dir"]) {
let value;
try {
const args = ["config", "get", key, "-g", `--config.global-dir=${owner.globalDir}`, `--config.global-bin-dir=${owner.globalBinDir}`];
const result = runPnpm(args, true);
const lines = outputText(result?.stdout).split(/\r?\n/).map(line => line.trim()).filter(Boolean);
if (result?.status !== 0 || lines.length !== 1) throw new Error();
value = lines[0];
} catch { return { ok: false, reason: "pnpm virtual-store configuration could not be resolved" }; }
if (/^(?:undefined|null)$/i.test(value)) continue;
if (!isAbsolutePath(value, platform)) return { ok: false, reason: "pnpm virtual-store directory is not absolute" };
let path;
try { path = realpathSync.native(value); if (!statSync(path).isDirectory()) throw new Error(); }
catch { return { ok: false, reason: "pnpm virtual-store directory could not be resolved" }; }
const rel = relative(store, path);
if (rel === ".." || rel.startsWith("../") || rel.startsWith("..\\") || isAbsolute(rel)) {
return { ok: false, reason: "pnpm virtual-store directory is outside the selected store" };
}
virtualStoreDirs.push(path);
}
if (owner?.virtualStoreDirs && (owner.virtualStoreDirs.length !== virtualStoreDirs.length
|| virtualStoreDirs.some((path, index) => lexicalPathKey(path, platform) !== lexicalPathKey(owner.virtualStoreDirs[index], platform)))) {
return { ok: false, reason: "pnpm virtual-store configuration changed" };
}
return { ok: true, store, storePath, virtualStoreDirs, homeAnchor };
}
function isPackageInGlobalStore(packagePath, store) {
const path = realpathSync.native(packagePath);
const rel = relative(store, path);
return rel !== ".." && !rel.startsWith("../") && !rel.startsWith("..\\") && !isAbsolute(rel);
}
/**
* Read and verify the package manager's active global link. `owner` constraints
* make the listing a proof of the group selected during preflight, not merely a
* successful listing from whichever pnpm happens to be first on PATH.
*/
export function readPnpmGlobalPackage(
packageName,
runPnpm,
verify = verifyPnpmInstallTree,
constraints = {},
) {
const platform = constraints.platform ?? process.platform;
const expectedGlobalDir = constraints.expectedGlobalDir ?? constraints.owner?.globalDir;
const expectedGlobalRoot = constraints.expectedGlobalRoot ?? constraints.owner?.globalRoot;
const globalBinDir = constraints.globalBinDir ?? constraints.owner?.globalBinDir;
if (constraints.owner?.globalStore === true) {
const unsafe = windowsCmdPathRefusal(constraints.owner, constraints.env, platform);
if (unsafe) return unsafe;
}
let result;
try {
result = runPnpm(ownerGlobalArgs(["list", "-g", "--depth=0", "--json", packageName], constraints.owner), true);
} catch {
return { ok: false, reason: "pnpm global package listing failed" };
}
if (result?.status !== 0) return { ok: false, reason: "pnpm global package listing failed" };
const inspected = inspectListOutput(result.stdout, packageName);
const entry = inspected?.entry;
const version = typeof entry?.version === "string" ? entry.version.trim() : "";
const packagePath = typeof entry?.path === "string" ? entry.path : "";
if (!version || !packagePath || !isAbsolutePath(packagePath, platform)) {
return { ok: false, reason: "pnpm did not report a valid active global package" };
}
if (constraints.expectedPackagePath && !samePath(packagePath, constraints.expectedPackagePath, platform)) {
return { ok: false, reason: "pnpm active package is not the running package" };
}
const rootPath = normaliseGlobalRoot(inspected?.root?.path, platform);
if (expectedGlobalRoot || expectedGlobalDir) {
// pnpm versions have reported either the global group or its node_modules root;
// accept both, but require the root when the caller is proving ownership. Without
// it a successful package listing cannot distinguish a command that ignored the
// pinned group from the selected group.
if (!rootPath) return { ok: false, reason: "pnpm did not report the selected global group" };
const rootMatches = expectedGlobalRoot
? samePath(rootPath, expectedGlobalRoot, platform)
: globalRootMatchesDir(rootPath, expectedGlobalDir, platform);
if (!rootMatches) return { ok: false, reason: "pnpm listed a different global group" };
}
let tree;
// A legacy global group keeps the verification it had before global-store support: no store
// query, no store argument. The verifier still refuses any package that uses store links
// without a selected store, so a global-store layout cannot pass on this branch.
const globalStore = constraints.owner?.globalStore === true;
let storeResult = { ok: true };
if (globalStore) {
storeResult = readPnpmStore(runPnpm, constraints.owner, platform, constraints.env);
if (!storeResult.ok) return storeResult;
// The global group is the other hop root; a link in its spelling would widen it the same way.
try {
const refusal = rootPath ? spellingRefusal(rootPath, "pnpm global group") : "pnpm global group has a symbolic link component";
if (refusal) return { ok: false, reason: refusal };
} catch { return { ok: false, reason: "pnpm global group could not be resolved" }; }
try {
if (!isPackageInGlobalStore(packagePath, storeResult.store)) return { ok: false, reason: "pnpm global-store package is outside the selected store" };
} catch { return { ok: false, reason: "pnpm active package path could not be resolved" }; }
}
const verifyPath = path => globalStore
? verify(path, version, storeResult.store, rootPath, storeResult.storePath)
: verify(path, version);
try {
tree = verifyPath(packagePath);
if (tree?.ok && constraints.expectedPackagePath && constraints.expectedPackagePath !== packagePath) {
tree = verifyPath(constraints.expectedPackagePath);
}
} catch {
return { ok: false, reason: "the active pnpm package could not be verified" };
}
if (!tree?.ok) return { ok: false, reason: tree?.failures?.[0] ?? "the active pnpm package failed verification" };
// A valid package tree/group is enough to bind the owner before an update. The
// existing shim may be stale from an older pnpm run; post-update and rollback
// reads leave this enabled so a successful transaction must produce fresh shims.
if (globalBinDir && constraints.checkShims !== false) {
const shims = (constraints.verifyShims ?? verifyPnpmGlobalShims)(
packagePath,
globalBinDir,
platform,
);
if (!shims?.ok) return { ok: false, reason: shims?.reason ?? "pnpm global shims failed verification" };
}
return {
ok: true,
version,
path: packagePath,
globalDir: expectedGlobalDir,
globalRoot: rootPath || expectedGlobalRoot,
globalBinDir,
...(globalStore ? {
store: storeResult.store,
storePath: storeResult.storePath,
virtualStoreDirs: storeResult.virtualStoreDirs,
homeAnchor: storeResult.homeAnchor,
} : {}),
};
}
function statusText(status) {
return status === null || status === undefined ? "?" : String(status);
}
function packageSpec(packageName, versionOrTag) {
return `${packageName}@${versionOrTag}`;
}
function listGlobalPackage(commandPath, packageName, runPnpm) {
try {
return runPnpm(commandPath, ["list", "-g", "--depth=0", "--json", packageName], true);
} catch {
return null;
}
}
/**
* Find the pnpm executable and global group that own the running package. Every
* candidate is inspected independently; this matters when two pnpm homes expose
* the same pnpm version but only one owns the current package/shim.
*/
export function resolvePnpmGlobalOwner({
packageName,
packagePath,
commandPaths,
runningShimPath,
runPnpm,
verify = verifyPnpmInstallTree,
platform = process.platform,
env = process.env,
// Re-resolving an owner already pinned to a store (orchestrated post-update verification) always runs
// the store proof, whatever the new tree's spelling, so a pinned store owner is never demoted.
requireStoreProof = false,
}) {
if (!isAbsolutePath(packagePath, platform)) return { ok: false, reason: "running pnpm package path is not absolute" };
let lastReason = "no pnpm global installation owns the running package";
// A running package that looks like a pnpm global store gets the remedy even when no pnpm candidate lists
// it (a failed listing, or another path), so every refusal of a store-like install says what to run.
let runningClassified;
try { runningClassified = requireStoreProof === true || pnpmPackageUsesGlobalStoreLinks(packagePath); }
catch { runningClassified = true; }
const withRunningHint = reason => runningClassified && typeof reason === "string" && !reason.endsWith(STORE_PROOF_HINT)
? reason + STORE_PROOF_HINT : reason;
for (const commandPath of commandPaths ?? []) {
const list = listGlobalPackage(commandPath, packageName, runPnpm);
if (list?.status !== 0) continue;
const inspected = inspectListOutput(list.stdout, packageName);
const listedPath = typeof inspected?.entry?.path === "string" ? inspected.entry.path : "";
if (!listedPath || !isAbsolutePath(listedPath, platform) || !samePath(listedPath, packagePath, platform)) continue;
// Classification only decides which proof is required. Either spelling of the running package
// that passes through pnpm store links demands the store proof; nothing here accepts a package.
// It runs before any refusal below so every refusal of a store-like install carries the remedy.
let globalStore;
try {
globalStore = requireStoreProof === true
|| pnpmPackageUsesGlobalStoreLinks(listedPath) || pnpmPackageUsesGlobalStoreLinks(packagePath);
} catch { globalStore = true; }
// A path that looks like a pnpm global store is accepted only on pnpm's own store answer. Every refusal of
// such an install says so, so a user whose group merely sits under a store-like directory, or whose pnpm
// home cannot be passed safely, knows why and what to run instead. The original reason stays the prefix.
const refusal = reason => globalStore && typeof reason === "string" ? reason + STORE_PROOF_HINT : reason;
const paths = resolveGlobalPaths(commandPath, runPnpm, inspected?.root?.path, platform);
if (!paths) {
lastReason = refusal("pnpm owns the running package but did not report its global group and bin directory");
continue;
}
const { globalDir, globalRoot, globalBinDir } = paths;
// If the process was entered through a generated command shim, its directory is
// another owner fact. This disambiguates two pnpm homes that expose the same pnpm
// version and (for example after a copied prefix) report the same package path.
// Direct `node bin/ocx.mjs` and Windows shims that invoke the package path do not
// provide a usable shim path, so they continue to rely on the package/group proof.
if (runningShimPath) {
const shimName = String(runningShimPath).replaceAll("\\", "/").split("/").at(-1)?.toLowerCase();
const isCommandShim = ["ocx", "opencodex", "ocx.cmd", "opencodex.cmd", "ocx.ps1", "opencodex.ps1"].includes(shimName ?? "");
if (isCommandShim && !samePath(dirname(runningShimPath), globalBinDir, platform)) {
lastReason = refusal("pnpm package owner did not match the running global shim");
continue;
}
}
const owner = { commandPath, packagePath: listedPath, globalDir, globalRoot, globalBinDir, ...(globalStore ? { globalStore: true } : {}) };
const active = readPnpmGlobalPackage(
packageName,
(args, capture = false) => runPnpm(commandPath, args, capture, owner),
verify,
{
owner,
expectedPackagePath: packagePath,
expectedGlobalDir: globalDir,
expectedGlobalRoot: globalRoot,
globalBinDir,
// Owner binding must remain possible when an older pnpm invocation left
// the top-level shim stale; the transaction verifies it after mutation.
checkShims: false,
platform,
env,
},
);
if (active.ok) {
return { ok: true, owner: { ...owner, packagePath: active.path, version: active.version,
...(globalStore ? { store: active.store, storePath: active.storePath, virtualStoreDirs: active.virtualStoreDirs, homeAnchor: active.homeAnchor } : {}) } };
}
lastReason = refusal(active.reason);
}
return { ok: false, reason: withRunningHint(lastReason) };
}
/**
* Update a pnpm global package through pnpm itself. Never rename or remove files in
* the pnpm store. Every command is pinned to the owner discovered before the proxy
* is stopped. The pre-update proof accepts an existing stale shim; success and
* rollback require a valid tree plus fresh generated shims.
*/
export function runPnpmGlobalUpdate({
packageName,
currentVersion,
targetVersion,
tag,
owner,
runningPackagePath,
runPnpm,
verify = verifyPnpmInstallTree,
verifyShims = verifyPnpmGlobalShims,
platform = process.platform,
log = () => {},
}) {
// A store owner's refusals during the update carry the same cause and remedy as discovery's.
const storeOwnerRefusal = reason => owner?.globalStore === true && typeof reason === "string" ? reason + STORE_PROOF_HINT : reason;
if (
!owner?.commandPath
|| !owner?.globalDir
|| !owner?.globalRoot
|| !owner?.globalBinDir
|| !isAbsolutePath(owner.commandPath, platform)
|| !isAbsolutePath(owner.globalDir, platform)
|| !isAbsolutePath(owner.globalBinDir, platform)
|| (owner.globalStore && (
!isAbsolutePath(owner.store, platform)
|| !isAbsolutePath(owner.storePath, platform)
|| !isAbsolutePath(owner.homeAnchor, platform)
|| !Array.isArray(owner.virtualStoreDirs)))
|| (!owner.globalStore && (owner.store !== undefined || owner.storePath !== undefined))
) {
return { ok: false, phase: "preflight", error: storeOwnerRefusal("pnpm global owner was not pinned") };
}
const constraints = {
owner,
expectedPackagePath: runningPackagePath ?? owner.packagePath,
expectedGlobalDir: owner.globalDir,
expectedGlobalRoot: owner.globalRoot,
globalBinDir: owner.globalBinDir,
verifyShims,
platform,
};
const before = readPnpmGlobalPackage(
packageName,
runPnpm,
verify,
{ ...constraints, checkShims: false },
);
if (!before.ok) return { ok: false, phase: "preflight", error: storeOwnerRefusal(before.reason) };
if (currentVersion && before.version !== currentVersion) {
return { ok: false, phase: "preflight", error: storeOwnerRefusal("pnpm's active package does not match the running package") };
}
const identity = owner.globalStore ? pinStoreOwnerIdentity(owner) : null;
const identityRefusal = identity?.refusal();
if (identityRefusal) return { ok: false, phase: "preflight", error: storeOwnerRefusal(identityRefusal) };
const requested = targetVersion || tag;
const spec = packageSpec(packageName, requested);
log(`Updating ${spec} with pnpm…`);
let install;
try {
install = runPnpm(ownerGlobalArgs(["add", "-g", PNPM_BUILD_APPROVAL, spec], owner), false);
} catch {
install = { status: null, processTreeExited: false };
}
if (!Number.isInteger(install?.status) || install?.processTreeExited === false || install?.groupExited === false) return { ok: false, phase: "install", processTreeExited: false, rolledBack: false, uncertain: true,
error: "installer-termination-unconfirmed" };
// The package path may switch to a different group link, so only constrain
// the group/bin pair after the command; the active package path is intentionally open.
const after = readPnpmGlobalPackage(
packageName,
runPnpm,
verify,
{ ...constraints, expectedPackagePath: undefined },
);
if (!after.ok && isStoreProofFailure(after.reason)) {
return { ok: false, phase: "install", rolledBack: false, error: storeOwnerRefusal(after.reason) };
}
const targetMatches = after.ok && (!targetVersion || after.version === targetVersion);
if (install?.status === 0 && targetMatches) {
return {
ok: true,
phase: "done",
version: after.version,
path: after.path,
globalDir: owner.globalDir,
globalBinDir: owner.globalBinDir,
};
}
const installReason = install?.status !== 0
? `pnpm update failed (${statusText(install?.status)})`
: after.ok
? "pnpm update produced an unexpected active package version"
: `pnpm update completed but the active package failed verification: ${after.reason}`;
// A failed command may have left the original active group intact. Do not create a
// second update transaction in that case; the verified previous package is already safe.
if (after.ok && after.version === before.version) {
return {
ok: false,
phase: "install",
rolledBack: true,
rollbackPerformed: false,
activePath: after.path,
globalDir: owner.globalDir,
globalBinDir: owner.globalBinDir,
error: storeOwnerRefusal(`${installReason}; previous version remains active`),
};
}
// A failed listing says nothing about the effective store: bind it again before
// issuing a rollback mutation, independently of whether readback succeeded.
if (owner.globalStore) {
const rollbackStore = readPnpmStore(runPnpm, owner, platform);
if (!rollbackStore.ok) return { ok: false, phase: "rollback", rolledBack: false, error: storeOwnerRefusal(rollbackStore.reason) };
// The global group is the other root every link hop is confined to: a rollback must not write through a
// group that has gained a link component or lost its canonical spelling since discovery.
let groupRefusal;
try { groupRefusal = spellingRefusal(owner.globalRoot, "pnpm global group"); }
catch { groupRefusal = "pnpm global group could not be resolved"; }
if (groupRefusal) return { ok: false, phase: "rollback", rolledBack: false, error: storeOwnerRefusal(groupRefusal) };
const replaced = identity?.refusal();
if (replaced) return { ok: false, phase: "rollback", rolledBack: false, error: storeOwnerRefusal(replaced) };
}
log(`Restoring ${packageName}@${before.version} with pnpm…`);
let rollback;
try {
rollback = runPnpm(ownerGlobalArgs(["add", "-g", PNPM_BUILD_APPROVAL, packageSpec(packageName, before.version)], owner), false);
} catch {
rollback = { status: null, processTreeExited: false };
}
if (!Number.isInteger(rollback?.status) || rollback?.processTreeExited === false || rollback?.groupExited === false) return { ok: false, phase: "rollback", processTreeExited: false, rolledBack: false, uncertain: true,
error: "installer-termination-unconfirmed" };
const restored = readPnpmGlobalPackage(
packageName,
runPnpm,
verify,
{ ...constraints, expectedPackagePath: undefined },
);
if (rollback?.status === 0 && restored.ok && restored.version === before.version) {
return {
ok: false,
phase: "rollback",
rolledBack: true,
rollbackPerformed: true,
activePath: restored.path,
globalDir: owner.globalDir,
globalBinDir: owner.globalBinDir,
error: storeOwnerRefusal(`${installReason}; previous version restored`),
};
}
// The readback's own reason (a store-proof failure included) leads, so the user sees why first.
const unverifiedPrefix = restored.ok || typeof restored.reason !== "string" ? "" : `${restored.reason}; `;
return {
ok: false,
phase: "rollback",
rolledBack: false,
rollbackPerformed: false,
...(restored.ok ? { activePath: restored.path } : {}),
globalDir: owner.globalDir,
globalBinDir: owner.globalBinDir,
error: storeOwnerRefusal(`${unverifiedPrefix}${installReason}; previous version could not be verified after rollback`),
};
}