UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

522 lines (496 loc) • 24.7 kB
/** * Transactional npm self-update: stage -> verify -> swap -> rollback (#1942 / #1849). * * The legacy path ran `npm install -g` straight into the live global tree, so a * failure after npm removed the old files left a file-less package skeleton with no * recovery. This module stages the new version into a SIBLING directory of the live * package (same volume, so directory renames are atomic-ish and never cross devices), * verifies the staged tree with a manifest before anything live is touched, then swaps * live -> backup -> stage-into-live with a reverse-rename rollback on failure and a * recovery marker on double fault. * * Layout (siblings, never children — a child would travel WITH the live rename and the * live dir cannot move into its own subtree): * <scopeDir>/opencodex live package * <scopeDir>/.ocx-staging-<ts>/ npm --prefix root (contains node_modules/...) * <scopeDir>/.ocx-backup-<ts>/opencodex previous live tree during/after the swap * <scopeDir>/.ocx-recovery.json double-fault marker with a one-line restore * * A staging directory is created exclusively and immediately carries an ownership marker * (`.ocx-update-owner.json`). Later updates report leftovers but do not delete them: a marker * proves provenance only while this process owns the fresh path, not after another local * process could have replaced it. Other neighbouring entries are likewise left alone (#5624). */ import { spawnSync } from "node:child_process"; import { randomBytes } from "node:crypto"; import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs"; import { basename, dirname, join } from "node:path"; /** * Dependency lookup confined to the candidate's OWN tree. This is the npm contract and it * must stay lexical: Node's resolver walks the ancestor directory chain, so a global npm * candidate at <prefix>/lib/node_modules/@scope/pkg could satisfy its bundled-Bun * requirement from <prefix>/lib/node_modules/bun, which belongs to a different package. * That verdict is not cosmetic — it accepts a stage that cannot start (D2), skips the * post-swap rollback, and lets bootRestoreProbe reap the only known-good backup. */ function candidateTreeDependencyDir(packageDir, name) { const dir = join(packageDir, "node_modules", ...name.split("/")); return existsSync(join(dir, "package.json")) ? dir : undefined; } /** * The candidate's own bun directory, whether or not it carries a readable package.json. * The size gate keys on the DIRECTORY, matching the pre-carry verifier: a half-extracted * node_modules/bun holding a truncated binary and no manifest is still a broken tree, and * bun is not always among the sentinels, so the sentinel loop cannot be relied on to catch it. */ function ownTreeBunDir(packageDir) { const dir = join(packageDir, "node_modules", "bun"); return existsSync(dir) ? dir : undefined; } /** The node_modules directory a package sits directly inside, or undefined. */ function enclosingNodeModules(packageDir) { const parent = dirname(packageDir); if (basename(parent) === "node_modules") return parent; // Scoped packages live one level deeper: <node_modules>/@scope/name. const grandparent = dirname(parent); if (basename(parent).startsWith("@") && basename(grandparent) === "node_modules") return grandparent; return undefined; } /** pnpm's own bookkeeping at the root of a node_modules tree it manages. */ function isPnpmManagedRoot(nodeModulesDir) { if (!nodeModulesDir) return false; if (nodeModulesDir.split(/[\\/]/).includes(".pnpm")) return true; return existsSync(join(nodeModulesDir, ".pnpm")) || existsSync(join(nodeModulesDir, ".modules.yaml")); } /** * Dependency roots this package INSTANCE owns. pnpm exposes dependencies in several shapes — * symlinks inside the package's own node_modules, a package root that is itself a symlink into * the virtual store, or a hoisted group root — so the npm rule alone rejects healthy trees. * Ownership is still bounded: an enclosing node_modules counts only when pnpm's own metadata * says pnpm manages it, which keeps an unrelated ancestor installation out. */ function ownedDependencyRoots(packageDir) { const roots = []; const add = dir => { if (dir && !roots.includes(dir)) roots.push(dir); }; const lexicalGroup = enclosingNodeModules(packageDir); add(join(packageDir, "node_modules")); let real; try { real = realpathSync(packageDir); } catch { /* keep the lexical path only */ } if (real && real !== packageDir) add(join(real, "node_modules")); if (isPnpmManagedRoot(lexicalGroup)) add(lexicalGroup); const realGroup = real ? enclosingNodeModules(real) : undefined; if (isPnpmManagedRoot(realGroup)) add(realGroup); return roots; } /** * pnpm dependency lookup. Probing the owned roots directly, rather than filtering whatever * Node's resolver returned, is deliberate: require.resolve reports the REALPATH of the * resolved file, so a dependency reached through pnpm's own node_modules symlink comes back * as a virtual-store path that no lexical ownership test can recognise. existsSync follows * the symlink, which is exactly the pnpm graph edge that proves ownership. */ function pnpmOwnedDependencyDir(packageDir, name) { for (const root of ownedDependencyRoots(packageDir)) { const dir = join(root, ...name.split("/")); if (existsSync(join(dir, "package.json"))) return dir; } return undefined; } /** Verification manifest for a staged (or live) package tree. */ function verifyTreeWithDependencyLookup(packageDir, expectedVersion, dependencyDir) { const failures = []; let pkg; try { pkg = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8")); } catch (error) { return { ok: false, failures: ["package.json unreadable: " + (error?.message ?? String(error))] }; } if (expectedVersion && pkg.version !== expectedVersion) { failures.push("package.json version " + pkg.version + " != expected " + expectedVersion); } const launcher = join(packageDir, "bin", "ocx.mjs"); try { const st = statSync(launcher); if (!st.isFile() || st.size < 1024) failures.push("bin/ocx.mjs missing or truncated"); } catch { failures.push("bin/ocx.mjs absent"); } // The bundled Bun binary is the load-bearing artifact: without it the launcher exits // before serving anything, and a boot probe that called this tree healthy would reap // the only backup (review High 3). Size-gate the real binary, not just its package.json. const bunPkgDir = dependencyDir(packageDir, "bun") ?? ownTreeBunDir(packageDir); if (bunPkgDir) { const bunBinary = findLargestFile(bunPkgDir); if (!bunBinary || bunBinary.size < 10 * 1024 * 1024) { failures.push("bundled Bun binary missing or truncated (< 10MB)"); } } // Sentinel direct deps: each must have an intact package.json. The bundled Bun dep is // the load-bearing one — without it the launcher cannot start the proxy at all. const deps = Object.keys(pkg.dependencies ?? {}); const sentinels = deps.filter(name => name === "bun" || name === "zod").length > 0 ? deps.filter(name => name === "bun" || name === "zod") : deps.slice(0, 2); for (const name of sentinels) { if (!dependencyDir(packageDir, name)) failures.push("sentinel dependency missing: " + name); } return failures.length === 0 ? { ok: true, failures: [] } : { ok: false, failures }; } /** * npm (and every recovery decision): the candidate must be self-contained. Used by * transactionalNpmUpdate's stage and post-swap checks and by bootRestoreProbe. */ export function verifyInstallTree(packageDir, expectedVersion) { return verifyTreeWithDependencyLookup(packageDir, expectedVersion, candidateTreeDependencyDir); } /** * Verify a package exposed through pnpm's global virtual store. pnpm 10/11 may use an * isolated virtual store, a custom virtualStoreDir, global virtual-store links, or a * hoisted linker, so the dependency may sit outside the package directory — but it must * still be reachable through a root this package instance owns. */ export function verifyPnpmInstallTree(packageDir, expectedVersion) { return verifyTreeWithDependencyLookup(packageDir, expectedVersion, pnpmOwnedDependencyDir); } function stampedName(prefix) { return prefix + "-" + new Date().toISOString().replace(/[:.]/g, "-"); } export const UPDATE_OWNER_MARKER = ".ocx-update-owner.json"; const STAGE_PREFIX = ".ocx-staging-"; /** * A marked stage younger than this is reported as recent. npm's staging install is bounded at * three minutes by the launcher; the floor distinguishes likely in-flight work from leftovers. */ export const STALE_STAGE_MIN_AGE_MS = 30 * 60 * 1000; const RETRYABLE_REMOVE_CODES = new Set(["EPERM", "EBUSY", "EACCES", "ENOTEMPTY"]); /** Create a fresh staging directory that did not exist before, and mark it as ours. */ function createOwnedStage(scopeDir, pkgName, deps = {}) { const mkdir = deps.mkdir ?? mkdirSync; const stageRoot = join(scopeDir, stampedName(".ocx-staging") + "-" + randomBytes(4).toString("hex")); // Not recursive: an existing directory of the same name must fail, never be reused. mkdir(stageRoot); try { writeFileSync(join(stageRoot, UPDATE_OWNER_MARKER), JSON.stringify({ schema: 1, kind: "staging", pkgName, pid: process.pid, createdAt: (deps.now ?? Date.now)(), }), { flag: "wx" }); // npm's strict script policy plans the global tree before it creates the prefix layout, so // `-g --prefix` into a bare stage fails with ENOENT on <stage>/lib (#5760). POSIX global // prefixes keep packages under lib/; Windows installs into the prefix itself. if (process.platform !== "win32") mkdir(join(stageRoot, "lib")); } catch (error) { // Created by this call and not yet handed to npm: remove it rather than leave a partial stage. try { rmSync(stageRoot, { recursive: true, force: true }); } catch { /* reported by the caller */ } throw error; } return stageRoot; } /** The marker of a real (non-link) staging directory this updater created, or null. */ function readOwnedStageMarker(dir, pkgName) { try { const dirStat = lstatSync(dir); // A symlink or junction is never ours to delete: removing through it reaches its target. if (!dirStat.isDirectory() || dirStat.isSymbolicLink()) return null; const markerPath = join(dir, UPDATE_OWNER_MARKER); if (!lstatSync(markerPath).isFile()) return null; const marker = JSON.parse(readFileSync(markerPath, "utf8")); if (marker?.schema !== 1 || marker.kind !== "staging" || marker.pkgName !== pkgName) return null; if (typeof marker.createdAt !== "number" || !Number.isFinite(marker.createdAt)) return null; return marker; } catch { return null; } } function removeWithRetry(rm, target, attempts = 3) { for (let attempt = 0; ; attempt += 1) { try { rm(target, { recursive: true, force: true }); return null; } catch (error) { const code = typeof error?.code === "string" ? error.code : "EUNKNOWN"; if (!RETRYABLE_REMOVE_CODES.has(code) || attempt >= attempts - 1) return code; const until = Date.now() + 100 * (attempt + 1); while (Date.now() < until) { /* brief synchronous backoff, as renameWithRetry */ } } } } /** * Remove an owned staging directory. The marker goes last and only once everything else is * gone, so a tree held open by a running executable (the reported locked `bunx.exe`) stays * provably ours and the next update can finish the job. */ export function removeOwnedStage(stageRoot, deps = {}) { const rm = deps.rm ?? rmSync; let names; try { names = readdirSync(stageRoot); } catch (error) { return error?.code === "ENOENT" ? { removed: true } : { removed: false, code: error?.code ?? "EUNKNOWN" }; } let failure = null; for (const name of names) { if (name === UPDATE_OWNER_MARKER) continue; const code = removeWithRetry(rm, join(stageRoot, name)); if (code && !failure) failure = code; } if (failure) return { removed: false, code: failure }; const markerCode = removeWithRetry(rm, join(stageRoot, UPDATE_OWNER_MARKER)); if (markerCode) return { removed: false, code: markerCode }; const dirCode = removeWithRetry(rm, stageRoot); return dirCode ? { removed: false, code: dirCode } : { removed: true }; } /** * Report what earlier update attempts left next to the package. A marker is forgeable and a * pathname can be replaced after inspection, so no later process may recursively delete a * leftover by that pathname. Never throws or fails the update: fresh unique stages step around it. */ export function sweepUpdateLeftovers({ packageDir, pkgName, log = () => {}, deps = {} }) { const scopeDir = dirname(packageDir); const now = (deps.now ?? Date.now)(); const result = { inUse: [], recent: [], notOwned: [] }; let names = []; try { names = readdirSync(scopeDir); } catch { return result; } // npm renames a package it is replacing to ".<name>-<random>" during a direct global install. const renameAsidePrefix = "." + basename(packageDir) + "-"; for (const name of names.sort()) { const full = join(scopeDir, name); if (name.startsWith(STAGE_PREFIX)) { const marker = readOwnedStageMarker(full, pkgName); if (!marker) { result.notOwned.push(full); } else if (now - marker.createdAt < STALE_STAGE_MIN_AGE_MS) { result.recent.push(full); } else { result.inUse.push({ path: full, code: "ESTALE" }); } } else if (name.startsWith(renameAsidePrefix)) { result.notOwned.push(full); } } // Names only: the full path under a user-scoped npm prefix carries the account name, and // this logger is the launcher's console. for (const entry of result.inUse) { log(entry.code === "ESTALE" ? "Left an earlier update's staging directory in place; delete it by hand once no OpenCodex process is running from it: " + basename(entry.path) : "Left an earlier update's staging directory in place (could not remove it: " + entry.code + "): " + basename(entry.path)); } for (const path of result.notOwned) { log("Not removing " + basename(path) + " next to the package: this updater did not create it. Delete it by hand once no OpenCodex process is running from it."); } return result; } /** Whether the launcher that ran this npm update can still drive service/tray recovery. */ export function launcherUsableAfterNpmUpdate(tx) { return Boolean(tx?.ok || tx?.rolledBack === true || ["stage", "verify", "swap-backup"].includes(tx?.phase)); } /** Largest regular file under a directory tree (bounded depth) — locates the Bun binary. */ function findLargestFile(root, depth = 3) { let best; let names = []; try { names = readdirSync(root); } catch { return undefined; } for (const name of names) { const full = join(root, name); let st; try { st = statSync(full); } catch { continue; } if (st.isFile()) { if (!best || st.size > best.size) best = { path: full, size: st.size }; } else if (st.isDirectory() && depth > 0) { const sub = findLargestFile(full, depth - 1); if (sub && (!best || sub.size > best.size)) best = sub; } } return best; } /** Bounded Windows-class rename retry: EPERM/EBUSY/EACCES from AV/indexers clears in ms. */ function renameWithRetry(rename, from, to, attempts = 5) { for (let attempt = 0; ; attempt += 1) { try { rename(from, to); return; } catch (error) { const code = error?.code; const retryable = code === "EPERM" || code === "EBUSY" || code === "EACCES"; if (!retryable || attempt >= attempts - 1) throw error; // Synchronous bounded backoff (launcher context has no async loop here). const until = Date.now() + 100 * (attempt + 1); while (Date.now() < until) { /* spin briefly; total worst case ~1.5s */ } } } } function recoveryMarkerPath(scopeDir) { return join(scopeDir, ".ocx-recovery.json"); } /** Startup probe: restore a backup when the live tree is broken (D4 power-loss rows). */ export function bootRestoreProbe(packageDir, deps = {}) { const rename = deps.rename ?? renameSync; const scopeDir = dirname(packageDir); let backups = []; try { backups = readdirSync(scopeDir).filter(name => name.startsWith(".ocx-backup-")).sort(); } catch { return { action: "none" }; } if (backups.length === 0) return { action: "none" }; const liveOk = existsSync(join(packageDir, "package.json")) && verifyInstallTree(packageDir).ok; const newestBackup = join(scopeDir, backups[backups.length - 1], "opencodex"); if (liveOk) { // Live is healthy: the backups are leftovers from a completed swap. Reap them. for (const name of backups) { try { rmSync(join(scopeDir, name), { recursive: true, force: true }); } catch { /* keep */ } } try { rmSync(recoveryMarkerPath(scopeDir), { force: true }); } catch { /* keep */ } return { action: "reaped", count: backups.length }; } if (!existsSync(join(newestBackup, "package.json"))) return { action: "none" }; try { try { rmSync(packageDir, { recursive: true, force: true }); } catch { /* may not exist */ } rename(newestBackup, packageDir); return { action: "restored", from: newestBackup }; } catch (error) { return { action: "failed", error: error?.message ?? String(error) }; } } /** * Run the transactional update. `runNpm(args, opts)` is injected so the caller keeps * its hardened npm resolution (npm-invocation.mjs) and logging. */ export function transactionalNpmUpdate({ packageDir, pkgName, targetVersion, tag, runNpm, log = () => {}, deps = {}, }) { const rename = deps.rename ?? renameSync; const scopeDir = dirname(packageDir); // Leftovers from earlier attempts are only reported; fresh unique stages step around them. This never fails. try { sweepUpdateLeftovers({ packageDir, pkgName, log, deps }); } catch { /* report-only */ } let stageRoot; // GLOBAL-style staging (-g --prefix): npm nests the package's dependencies INSIDE the // package dir, exactly like the live global tree this stage will replace. A local-style // install would hoist bun/zod to stageRoot/node_modules — siblings that the swap would // leave behind, shipping a dependency-less live tree (release-audit blocker). // Layout: <stageRoot>/lib/node_modules/<pkg> on POSIX, <stageRoot>/node_modules/<pkg> // on Windows. // D1: stage to the side. --prefix keeps npm entirely inside stageRoot; the live tree // and the npm bin shims are untouched until the swap. A failure HERE (mkdir EACCES, // ENOSPC) must NOT fall back to the destructive legacy install (review High 4): the // caller sees a normal phase failure with live untouched. try { stageRoot = createOwnedStage(scopeDir, pkgName, deps); } catch (error) { return { ok: false, phase: "stage", error: "could not create staging directory: " + (error?.message ?? String(error)) }; } const stagedCandidatesIn = root => [ join(root, "lib", "node_modules", ...pkgName.split("/")), join(root, "node_modules", ...pkgName.split("/")), ]; const discardStage = () => { const removal = removeOwnedStage(stageRoot, deps); if (!removal.removed) { // EACCES/EUNKNOWN do not prove an open file, so the message names the failure // without blaming a process; the code stays for whoever reads the log. log("Left this update's staging directory in place (could not remove it: " + removal.code + "); later updates will not remove it either — delete it by hand once no OpenCodex process is running from it: " + basename(stageRoot)); } }; const spec = pkgName + "@" + (targetVersion || tag); log("Staging " + spec + " into " + basename(stageRoot) + " next to the package"); // npm 12 blocks lifecycle scripts by default. Bun's postinstall copies the selected // @oven/bun-* executable into bun/bin, so a successful npm exit without this narrow // approval leaves the staged tree intentionally incomplete. Allow only the package // whose executable the manifest verifies below; never broaden this to all scripts. const install = runNpm([ "install", "-g", "--prefix", stageRoot, "--allow-scripts=bun", "--no-audit", "--no-fund", spec, ]); if (install.status !== 0) { discardStage(); return { ok: false, phase: "stage", error: "npm staging install failed (" + (install.status ?? "?") + ")" }; } const stagedPackage = stagedCandidatesIn(stageRoot).find(dir => existsSync(join(dir, "package.json"))); if (!stagedPackage) { discardStage(); return { ok: false, phase: "verify", error: "staged package directory not found under " + stageRoot }; } // D2: verify INSIDE the stage. Live is still untouched on any failure here. const staged = verifyInstallTree(stagedPackage, targetVersion || undefined); if (!staged.ok) { discardStage(); return { ok: false, phase: "verify", error: "staged tree failed verification: " + staged.failures.join("; ") }; } // D3: swap. live -> backup, stage -> live, re-verify live, rollback on failure. const backupRoot = join(scopeDir, stampedName(".ocx-backup")); const backupPackage = join(backupRoot, "opencodex"); try { mkdirSync(backupRoot, { recursive: true }); } catch (error) { discardStage(); return { ok: false, phase: "swap-backup", error: "could not create backup directory: " + (error?.message ?? String(error)) }; } try { renameWithRetry(rename, packageDir, backupPackage); } catch (error) { discardStage(); try { rmSync(backupRoot, { recursive: true, force: true }); } catch { /* best effort */ } return { ok: false, phase: "swap-backup", error: "could not move live tree aside: " + (error?.message ?? String(error)) }; } try { renameWithRetry(rename, stagedPackage, packageDir); } catch (error) { // Rollback: reverse the first rename. Double fault leaves the recovery marker. try { renameWithRetry(rename, backupPackage, packageDir); discardStage(); try { rmSync(backupRoot, { recursive: true, force: true }); } catch { /* best effort */ } return { ok: false, phase: "swap-live", rolledBack: true, error: "could not place staged tree: " + (error?.message ?? String(error)) }; } catch (rollbackError) { writeFileSync(recoveryMarkerPath(scopeDir), JSON.stringify({ at: new Date().toISOString(), backup: backupPackage, live: packageDir, restore: 'move "' + backupPackage + '" back to "' + packageDir + '"', error: String(error?.message ?? error), rollbackError: String(rollbackError?.message ?? rollbackError), }, null, 2)); return { ok: false, phase: "double-fault", rolledBack: false, error: "swap and rollback both failed; recovery marker written at " + recoveryMarkerPath(scopeDir) }; } } const liveCheck = verifyInstallTree(packageDir, targetVersion || undefined); if (!liveCheck.ok) { try { // Move the rejected tree into our own stage instead of deleting it in place: a file held // open there must not turn a clean rollback into a double fault. The stage's marker keeps // it sweepable by the next update. renameWithRetry(rename, packageDir, join(stageRoot, "rejected")); renameWithRetry(rename, backupPackage, packageDir); discardStage(); try { rmSync(backupRoot, { recursive: true, force: true }); } catch { /* best effort */ } return { ok: false, phase: "post-verify", rolledBack: true, error: "live tree failed post-swap verification: " + liveCheck.failures.join("; ") }; } catch (rollbackError) { writeFileSync(recoveryMarkerPath(scopeDir), JSON.stringify({ at: new Date().toISOString(), backup: backupPackage, live: packageDir, restore: 'move "' + backupPackage + '" back to "' + packageDir + '"', error: "post-swap verification failed: " + liveCheck.failures.join("; "), rollbackError: String(rollbackError?.message ?? rollbackError), }, null, 2)); return { ok: false, phase: "double-fault", rolledBack: false, error: "post-verify rollback failed; recovery marker written" }; } } // Success: stage scaffolding is disposable now; the backup stays until the next // healthy boot reaps it (bootRestoreProbe) — the process that spawned this update may // still hold the old cwd. discardStage(); return { ok: true, phase: "done", backup: backupPackage }; }