@yansigit/opencodex 2.31.0

package/src/update/notify.ts

@@ -0,0 +1,263 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { atomicWriteFile, getConfigDir } from "../config";
+import { hasStarPromptRun } from "../cli/star-prompt";
+import { selfLaunchArgv } from "../lib/self-launch-argv";
+import {
+  type Channel,
+  currentVersion,
+  detectInstall,
+  latestVersion,
+  runUpdate,
+  updateCommandStr,
+  updateTag,
+} from "./index";
+
+const VERSION_FILENAME = "version.json";
+const REFRESH_INTERVAL_MS = 20 * 60 * 60 * 1000; // 20h, matching codex-rs
+const RELEASE_NOTES_URL = "https://github.com/lidge-jun/opencodex/releases/latest";
+
+export interface VersionCache {
+  latest_version: string;
+  /** ISO-8601 (RFC3339) timestamp of the last successful registry check. */
+  last_checked_at: string;
+  dismissed_version?: string;
+  tag: Channel;
+}
+
+function versionFilePath(): string {
+  return join(getConfigDir(), VERSION_FILENAME);
+}
+
+/**
+ * Read the cached version info. Returns null on any error or when the cached
+ * channel differs from the current one (so a stable<->preview switch re-fetches
+ * instead of comparing across channels).
+ */
+export function readVersionCache(channel: Channel): VersionCache | null {
+  try {
+    const raw = readFileSync(versionFilePath(), "utf8");
+    const parsed = JSON.parse(raw) as Partial<VersionCache>;
+    if (typeof parsed.latest_version !== "string" || typeof parsed.last_checked_at !== "string") return null;
+    if (parsed.tag !== channel) return null;
+    return {
+      latest_version: parsed.latest_version,
+      last_checked_at: parsed.last_checked_at,
+      dismissed_version: typeof parsed.dismissed_version === "string" ? parsed.dismissed_version : undefined,
+      tag: parsed.tag,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function writeVersionCache(cache: VersionCache): void {
+  try {
+    atomicWriteFile(versionFilePath(), `${JSON.stringify(cache)}\n`);
+  } catch {
+    /* best-effort; never block startup */
+  }
+}
+
+function parseStable(v: string): [number, number, number] | null {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+function parsePreview(v: string): [number, number, number, number] | null {
+  const m = /^(\d+)\.(\d+)\.(\d+)-preview\.(\d+)$/.exec(v.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+}
+
+function gt(a: number[], b: number[]): boolean {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    if (av !== bv) return av > bv;
+  }
+  return false;
+}
+
+/**
+ * Channel-aware "is latest newer than current?".
+ * - latest channel: compare maj.min.pat only; prerelease TARGETS are never
+ *   "newer" (parity with codex-rs), so stable users are not pushed onto
+ *   previews. An installed preview CURRENT compares by its maj.min.pat core,
+ *   so a stable release with a strictly higher base is offered (same base is
+ *   content-lateral promotion and stays not-newer, mirroring the preview
+ *   channel's O3 rule).
+ * - preview channel: preview-vs-preview compares the trailing -preview.N; a
+ *   stable release with a strictly higher base counts as newer (O3), while a
+ *   stable release with the same base as the current preview does not.
+ */
+export function isNewer(latest: string, current: string, channel: Channel): boolean {
+  if (channel === "latest") {
+    const l = parseStable(latest);
+    const c = parseStable(current) ?? parsePreview(current)?.slice(0, 3);
+    if (!l || !c) return false;
+    return gt(l, c);
+  }
+  // preview channel
+  const lPre = parsePreview(latest);
+  const cPre = parsePreview(current);
+  if (lPre && cPre) return gt(lPre, cPre);
+
+  const lStable = parseStable(latest);
+  if (lStable && cPre) {
+    // Stable release vs current preview: newer only if the base is strictly
+    // higher than the preview's base (equal base would be a downgrade nag).
+    return gt(lStable, [cPre[0], cPre[1], cPre[2]]);
+  }
+  const cStable = parseStable(current);
+  if (lStable && cStable) return gt(lStable, cStable);
+  return false;
+}
+
+export function isSourceBuildVersion(v: string): boolean {
+  return v.trim() === "0.0.0";
+}
+
+/** The interactive/TTY + install-method gate shared with the star prompt. */
+function interactiveGuardOk(): boolean {
+  return !(process.env.OCX_SERVICE || !process.stdin.isTTY || !process.stdout.isTTY);
+}
+
+/**
+ * Decide whether this run should even consider showing the prompt. Returns the
+ * channel + current version when eligible, else null. Eligibility requires a
+ * real global install, a non-source version, the interactive guard, and that
+ * the one-time star prompt has already run (first-run yield, O1).
+ */
+export function shouldConsider(): { channel: Channel; current: string } | null {
+  if (detectInstall() === "source") return null;
+  const current = currentVersion();
+  if (current === "?" || isSourceBuildVersion(current)) return null;
+  if (!interactiveGuardOk()) return null;
+  if (!hasStarPromptRun()) return null; // yield on the very first run
+  return { channel: updateTag(current), current };
+}
+
+/** The cached upgrade version to surface, honoring the user's dismissal. */
+export function getUpgradeVersionForPopup(
+  cache: VersionCache | null,
+  current: string,
+  channel: Channel,
+): string | null {
+  if (!cache) return null;
+  if (!isNewer(cache.latest_version, current, channel)) return null;
+  if (cache.dismissed_version === cache.latest_version) return null;
+  return cache.latest_version;
+}
+
+function cacheIsStale(cache: VersionCache | null): boolean {
+  if (!cache) return true;
+  const checked = Date.parse(cache.last_checked_at);
+  if (!Number.isFinite(checked)) return true;
+  return Date.now() - checked > REFRESH_INTERVAL_MS;
+}
+
+/**
+ * If the cache is missing or older than 20h, kick off a detached helper to
+ * refresh it without blocking this (soon-to-be daemon) process. Fire-and-forget.
+ */
+export function triggerBackgroundRefreshIfStale(channel: Channel, cache: VersionCache | null): void {
+  if (!cacheIsStale(cache)) return;
+  try {
+    const commandArgs = ["__refresh-version", channel];
+    const args = selfLaunchArgv(commandArgs);
+    if (args.length > commandArgs.length && (!args[0] || !existsSync(args[0]))) return;
+    const child = spawn(process.execPath, args, {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+      env: { ...process.env, OCX_SERVICE: "1" }, // never let the helper prompt
+    });
+    child.unref();
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Body of the hidden `__refresh-version` subcommand: fetch the latest version
+ * for the channel and persist it. Only advances `last_checked_at` on success so
+ * a failed fetch retries on the next start.
+ */
+export async function refreshVersionCache(channel: Channel): Promise<void> {
+  const latest = latestVersion(channel);
+  if (!latest) return; // do not dirty the cache or advance the timestamp
+  const prev = readVersionCache(channel);
+  writeVersionCache({
+    latest_version: latest,
+    last_checked_at: new Date().toISOString(),
+    dismissed_version: prev?.dismissed_version,
+    tag: channel,
+  });
+}
+
+/** Persist a dismissal so this exact version stops prompting. */
+function dismissVersion(channel: Channel, version: string): void {
+  const cache = readVersionCache(channel);
+  if (!cache) return;
+  writeVersionCache({ ...cache, dismissed_version: version });
+}
+
+function renderPrompt(current: string, latest: string, channel: Channel): string {
+  const command = updateCommandStr(detectInstall(), channel);
+  return [
+    "",
+    `  \x1b[38;5;141m✨ Update available!\x1b[0m  \x1b[2m${current} -> ${latest}\x1b[0m`,
+    "",
+    `  \x1b[2mRelease notes:\x1b[0m ${RELEASE_NOTES_URL}`,
+    "",
+    `  1) Update now (runs \`${command}\`)`,
+    "  2) Skip",
+    "  3) Skip until next version",
+    "",
+    "  [1/2/3] (default 1): ",
+  ].join("\n");
+}
+
+/**
+ * Interactive-only update prompt for `ocx start`. Must be called BEFORE the
+ * server binds a port / writes a PID, because "Update now" installs globally
+ * and exits. No-op for service/daemon/non-TTY runs and source checkouts.
+ * Never throws.
+ */
+export async function maybeShowUpdatePrompt(): Promise<void> {
+  try {
+    const eligible = shouldConsider();
+    if (!eligible) return;
+    const { channel, current } = eligible;
+
+    const cache = readVersionCache(channel);
+    triggerBackgroundRefreshIfStale(channel, cache);
+
+    const latest = getUpgradeVersionForPopup(cache, current, channel);
+    if (!latest) return;
+
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let answer = "";
+    try {
+      answer = (await rl.question(renderPrompt(current, latest, channel))).trim();
+    } finally {
+      rl.close();
+    }
+
+    const choice = answer === "" ? "1" : answer;
+    if (choice === "1") {
+      await runUpdate();
+      console.log("\nRestart the proxy:  ocx start");
+      process.exit(0);
+    } else if (choice === "3") {
+      dismissVersion(channel, latest);
+    }
+    // "2" (or anything else) -> Skip: continue this run unchanged.
+  } catch {
+    /* never let the update prompt disrupt startup */
+  }
+}

package/src/update/npm-cache-preflight.d.mts

@@ -0,0 +1,47 @@
+import type { spawnSync } from "node:child_process";
+
+export type NpmCachePreflightReason =
+  | "cache_accessible"
+  | "cache_entry_foreign_owner"
+  | "cache_entry_inaccessible"
+  | "cache_path_malformed"
+  | "inspection_incomplete"
+  | "npm_config_failed"
+  | "npm_unavailable"
+  | "windows_skip"
+  | "worker_failed"
+  | "worker_output_malformed"
+  | "worker_timeout";
+
+export interface NpmCachePreflightResult {
+  ok: boolean;
+  reason: NpmCachePreflightReason;
+}
+
+export interface NpmCacheInspectionOptions {
+  expectedUid?: number;
+  maxDepth?: number;
+  maxEntries?: number;
+  nowMs?: () => number;
+  /** Test seam: resolve a symlinked cache root. Defaults to realpathSync. */
+  realpathFn?: (path: string) => string;
+  /** Test seam: resolve an entry's owner uid. Defaults to the lstat result. */
+  uidOf?: (path: string, stat: { uid: number }) => number;
+  timeoutMs?: number;
+}
+
+export interface NpmCachePreflightOptions {
+  env?: NodeJS.ProcessEnv;
+  execPath?: string;
+  platform?: NodeJS.Platform;
+  spawnSyncFn?: typeof spawnSync;
+  timeoutMs?: number;
+}
+
+export function inspectNpmCacheDirectory(
+  cachePath: string,
+  options?: NpmCacheInspectionOptions,
+): NpmCachePreflightResult;
+
+export function runNpmCachePreflight(options?: NpmCachePreflightOptions): NpmCachePreflightResult;
+export function npmCachePreflightFailureMessage(reason: NpmCachePreflightReason): string;

package/src/update/npm-cache-preflight.mjs

@@ -0,0 +1,201 @@
+import { lstatSync, readdirSync, realpathSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { npmInvocation } from "./npm-invocation.mjs";
+
+const WORKER_ARG = "--ocx-npm-cache-preflight-worker";
+const PROTOCOL_VERSION = 1;
+const WORKER_TIMEOUT_MS = 10_000;
+const NPM_CONFIG_TIMEOUT_MS = 5_000;
+const INSPECTION_TIMEOUT_MS = 7_500;
+const MAX_ENTRIES = 100_000;
+const MAX_DEPTH = 64;
+
+const RESULT_REASONS = new Set([
+  "cache_accessible",
+  "cache_entry_foreign_owner",
+  "cache_entry_inaccessible",
+  "cache_path_malformed",
+  "inspection_incomplete",
+  "npm_config_failed",
+  "npm_unavailable",
+]);
+
+function inaccessibleByMode(stat) {
+  if (stat.isSymbolicLink()) return false;
+  const ownerBits = stat.mode & 0o700;
+  if (stat.isDirectory()) return (ownerBits & 0o700) !== 0o700;
+  return (ownerBits & 0o400) === 0;
+}
+
+/**
+ * Inspect an existing Unix npm cache without following symlinks. The limits are
+ * deliberately part of the result contract: an incomplete inspection cannot prove
+ * that replacing the live package will succeed.
+ */
+export function inspectNpmCacheDirectory(cachePath, options = {}) {
+  const expectedUid = options.expectedUid ?? process.getuid?.();
+  const deadline = (options.nowMs ?? Date.now)() + (options.timeoutMs ?? INSPECTION_TIMEOUT_MS);
+  const maxEntries = options.maxEntries ?? MAX_ENTRIES;
+  const maxDepth = options.maxDepth ?? MAX_DEPTH;
+  const nowMs = options.nowMs ?? Date.now;
+  // Injected uid seam. A test cannot create a genuinely foreign-owned file without a second
+  // account, and without this the symlink-before-ownership rule cannot be pinned: `!isDirectory`
+  // skips a link anyway, so removing the rule leaves every assertion green.
+  const uidOf = options.uidOf ?? ((_path, stat) => stat.uid);
+  const stack = [{ path: cachePath, depth: 0 }];
+  let inspected = 0;
+  let rootResolved = false;
+
+  while (stack.length > 0) {
+    // Budget exhausted is NOT a failure. A mature npm cache legitimately holds hundreds of
+    // thousands of entries — this machine's has ~256k — and treating "we ran out of time to
+    // look" as "your cache is broken" would block updates for ordinary users, which is worse
+    // than the bug this preflight exists to prevent. We looked at a bounded prefix, found
+    // nothing wrong, and let the update proceed.
+    if (inspected >= maxEntries || nowMs() > deadline) {
+      return { ok: true, reason: "inspection_incomplete" };
+    }
+    const current = stack.pop();
+    let stat;
+    try {
+      stat = lstatSync(current.path);
+    } catch (error) {
+      if (current.depth === 0 && error?.code === "ENOENT") {
+        return { ok: true, reason: "cache_accessible" };
+      }
+      return { ok: false, reason: "cache_entry_inaccessible" };
+    }
+    inspected += 1;
+
+    // A symlinked cache ROOT used to be rejected outright, but pointing ~/.npm at another volume
+    // is ordinary npm configuration, and blocking those users would be the same false-positive
+    // failure this preflight exists to avoid. Resolve the root once and inspect the target;
+    // only an unresolvable root is a real problem. Nested links are still never followed.
+    if (current.depth === 0 && stat.isSymbolicLink()) {
+      // Resolve exactly once. realpath already collapses a chain, so a second pass would only
+      // happen if the target is itself reported as a link — treat that as unresolvable rather
+      // than looping.
+      if (rootResolved) return { ok: false, reason: "cache_entry_inaccessible" };
+      rootResolved = true;
+      let resolved;
+      try {
+        resolved = (options.realpathFn ?? realpathSync)(current.path);
+      } catch {
+        return { ok: false, reason: "cache_entry_inaccessible" };
+      }
+      stack.push({ path: resolved, depth: 0 });
+      continue;
+    }
+    // A nested symlink is not. npm creates them constantly below _npx, node_modules and .bin,
+    // and we never follow them — so its owner is irrelevant and must not abort the update.
+    // This has to come BEFORE the ownership check: a foreign-owned but never-followed link is
+    // exactly the false positive that made the previous attempt at this feature unusable.
+    if (stat.isSymbolicLink()) continue;
+
+    if (expectedUid !== undefined && uidOf(current.path, stat) !== expectedUid) {
+      return { ok: false, reason: "cache_entry_foreign_owner" };
+    }
+    if (inaccessibleByMode(stat)) {
+      return { ok: false, reason: "cache_entry_inaccessible" };
+    }
+    if (!stat.isDirectory()) continue;
+    // Same reasoning as the entry budget: too deep to finish is not evidence of a bad cache.
+    if (current.depth >= maxDepth) return { ok: true, reason: "inspection_incomplete" };
+
+    let entries;
+    try {
+      entries = readdirSync(current.path, { withFileTypes: true });
+    } catch {
+      return { ok: false, reason: "cache_entry_inaccessible" };
+    }
+    for (const entry of entries) {
+      stack.push({ path: resolve(current.path, entry.name), depth: current.depth + 1 });
+    }
+  }
+
+  return { ok: true, reason: "cache_accessible" };
+}
+
+function workerResult() {
+  const invocation = npmInvocation(["config", "get", "cache"]);
+  if (!invocation) return { ok: false, reason: "npm_unavailable" };
+  const npm = spawnSync(invocation.file, invocation.args, {
+    encoding: "utf8",
+    timeout: NPM_CONFIG_TIMEOUT_MS,
+    windowsHide: true,
+    ...invocation.options,
+  });
+  if (npm.status !== 0) return { ok: false, reason: "npm_config_failed" };
+
+  const output = typeof npm.stdout === "string" ? npm.stdout.trim() : "";
+  if (!output || output.length > 4096 || output.includes("\0") || /[\r\n]/.test(output) || !isAbsolute(output)) {
+    return { ok: false, reason: "cache_path_malformed" };
+  }
+  return inspectNpmCacheDirectory(output);
+}
+
+// Reasons that legitimately accompany `ok: true`. The parser below cross-checks the flag against
+// this set so a worker cannot claim success with a failure reason (or the reverse). It is a SET,
+// not a single value: a bounded inspection that ran out of budget without finding a problem is a
+// pass, and hardcoding `cache_accessible` here silently rejected exactly that — the pass never
+// reached the caller and every large cache still failed, as `worker_output_malformed`.
+const OK_REASONS = new Set([
+  "cache_accessible",
+  "inspection_incomplete",
+  "windows_skip",
+]);
+
+function parseWorkerOutput(stdout) {
+  if (typeof stdout !== "string" || stdout.length > 1024) return null;
+  try {
+    const parsed = JSON.parse(stdout);
+    if (!parsed || parsed.protocol !== PROTOCOL_VERSION || typeof parsed.ok !== "boolean") return null;
+    if (typeof parsed.reason !== "string" || !RESULT_REASONS.has(parsed.reason)) return null;
+    if (parsed.ok !== OK_REASONS.has(parsed.reason)) return null;
+    if (Object.keys(parsed).sort().join(",") !== "ok,protocol,reason") return null;
+    return { ok: parsed.ok, reason: parsed.reason };
+  } catch {
+    return null;
+  }
+}
+
+/** Run the bounded cache inspection in an isolated, synchronously-timeboxed worker. */
+export function runNpmCachePreflight(options = {}) {
+  if ((options.platform ?? process.platform) === "win32") {
+    return { ok: true, reason: "windows_skip" };
+  }
+  const spawn = options.spawnSyncFn ?? spawnSync;
+  const result = spawn(
+    options.execPath ?? process.execPath,
+    [fileURLToPath(import.meta.url), WORKER_ARG],
+    {
+      encoding: "utf8",
+      timeout: options.timeoutMs ?? WORKER_TIMEOUT_MS,
+      windowsHide: true,
+      env: options.env ?? process.env,
+    },
+  );
+  if (result.status === null) return { ok: false, reason: "worker_timeout" };
+  if (result.status !== 0) return { ok: false, reason: "worker_failed" };
+  return parseWorkerOutput(result.stdout) ?? { ok: false, reason: "worker_output_malformed" };
+}
+
+/** Fixed operator guidance; worker/npm output is intentionally never interpolated. */
+export function npmCachePreflightFailureMessage(reason) {
+  return `npm cache access pre-flight failed (${reason}); fix cache ownership and permissions, then retry`;
+}
+
+const isWorker = process.argv[1]
+  && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+  && process.argv[2] === WORKER_ARG;
+if (isWorker) {
+  let result;
+  try {
+    result = workerResult();
+  } catch {
+    result = { ok: false, reason: "cache_entry_inaccessible" };
+  }
+  process.stdout.write(JSON.stringify({ protocol: PROTOCOL_VERSION, ...result }));
+}

package/src/update/npm-invocation.d.mts

@@ -0,0 +1,23 @@
+export interface NpmInvocationDeps {
+  cwd?: string;
+  exists?: (path: string) => boolean;
+}
+
+export interface NpmInvocation {
+  file: string;
+  args: string[];
+  options: { windowsVerbatimArguments?: boolean };
+}
+
+export declare function resolveNpmCommand(
+  platform?: NodeJS.Platform,
+  env?: Record<string, string | undefined>,
+  deps?: NpmInvocationDeps,
+): string | null;
+
+export declare function npmInvocation(
+  args: readonly string[],
+  platform?: NodeJS.Platform,
+  env?: Record<string, string | undefined>,
+  deps?: NpmInvocationDeps,
+): NpmInvocation | null;

package/src/update/npm-invocation.mjs

@@ -0,0 +1,94 @@
+import { existsSync } from "node:fs";
+import { win32 } from "node:path";
+
+const CMD_META = /([()%!^"`<>&|;, *?])/g;
+
+function escapeCmdArg(arg) {
+  let out = String(arg).replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, "$1$1");
+  return `"${out}"`.replace(CMD_META, "^$1");
+}
+
+function escapeCmdCommand(command) {
+  return command.replace(CMD_META, "^$1");
+}
+
+/**
+ * Whether a PATH entry *is* the current directory. The hijack this guards against is
+ * cmd.exe resolving a bare `npm` out of the directory opencodex was launched from, so
+ * only that exact directory has to be skipped — every candidate we hand to spawn is an
+ * absolute path, which is what actually defeats the implicit cwd-first search.
+ *
+ * Deliberately not a subtree test: npm's default Windows global prefix is
+ * `%AppData%\npm` (`C:\Users\x\AppData\Roaming\npm`), so excluding everything under the
+ * cwd would fail closed for anyone whose shell sits in their home directory — a normal
+ * setup, not the untrusted-project case this hardening is for.
+ */
+function isCurrentDirectory(cwd, entry) {
+  const left = win32.resolve(entry);
+  const right = win32.resolve(cwd);
+  return left.toLowerCase() === right.toLowerCase();
+}
+
+function cleanPathEntry(entry) {
+  const trimmed = entry.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) return trimmed.slice(1, -1);
+  return trimmed;
+}
+
+export function resolveNpmCommand(
+  platform = process.platform,
+  env = process.env,
+  deps = {},
+) {
+  if (platform !== "win32") return "npm";
+  const exists = deps.exists ?? existsSync;
+  const cwd = deps.cwd ?? process.cwd();
+  const extensions = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD")
+    .split(";")
+    .filter(Boolean);
+  const pathEntries = (env.PATH ?? env.Path ?? "")
+    .split(win32.delimiter)
+    .map(cleanPathEntry)
+    .filter(Boolean);
+
+  for (const entry of pathEntries) {
+    if (!win32.isAbsolute(entry)) continue;
+    if (isCurrentDirectory(cwd, entry)) continue;
+    for (const extension of extensions) {
+      const candidate = win32.join(entry, `npm${extension.toLowerCase()}`);
+      if (exists(candidate)) return win32.resolve(candidate);
+    }
+  }
+  return null;
+}
+
+function systemCommandProcessor(env) {
+  const systemRoot = env.SystemRoot ?? env.windir;
+  if (systemRoot && win32.isAbsolute(systemRoot)) {
+    return win32.join(systemRoot, "System32", "cmd.exe");
+  }
+  const comSpec = env.ComSpec;
+  return comSpec && win32.isAbsolute(comSpec) ? win32.resolve(comSpec) : null;
+}
+
+export function npmInvocation(
+  args,
+  platform = process.platform,
+  env = process.env,
+  deps = {},
+) {
+  const npm = resolveNpmCommand(platform, env, deps);
+  if (!npm) return null;
+  if (platform !== "win32" || !/\.(cmd|bat)$/i.test(npm)) {
+    return { file: npm, args: [...args], options: {} };
+  }
+
+  const commandProcessor = systemCommandProcessor(env);
+  if (!commandProcessor) return null;
+  const line = [escapeCmdCommand(npm), ...args.map(escapeCmdArg)].join(" ");
+  return {
+    file: commandProcessor,
+    args: ["/d", "/s", "/c", `"${line}"`],
+    options: { windowsVerbatimArguments: true },
+  };
+}

package/src/update/transactional-install.d.mts

@@ -0,0 +1,22 @@
+export type InstallTreeVerification = { ok: boolean; failures: string[] };
+export function verifyInstallTree(packageDir: string, expectedVersion?: string): InstallTreeVerification;
+export function bootRestoreProbe(
+  packageDir: string,
+  deps?: { rename?: (from: string, to: string) => void },
+): { action: "none" | "reaped" | "restored" | "failed"; count?: number; from?: string; error?: string };
+export function transactionalNpmUpdate(args: {
+  packageDir: string;
+  pkgName: string;
+  targetVersion?: string;
+  tag: string;
+  runNpm: (args: string[]) => { status: number | null };
+  log?: (line: string) => void;
+  deps?: { rename?: (from: string, to: string) => void };
+}): {
+  ok: boolean;
+  phase: "stage" | "verify" | "swap-backup" | "swap-live" | "post-verify" | "double-fault" | "done";
+  error?: string;
+  rolledBack?: boolean;
+  backup?: string;
+};
+