@xopcai/xopc 0.0.88 → 0.0.90

package/dist/src/infra/package-update-steps.js

@@ -0,0 +1,304 @@
+import { readPackageVersion } from "./package-json.js";
+import { XOPC_PACKAGE_NAME, collectInstalledGlobalPackageErrors, globalInstallArgs, globalInstallFallbackArgs, resolveExpectedInstalledVersionFromSpec, resolveGlobalInstallTarget, resolveNpmGlobalPrefixLayoutFromGlobalRoot, resolveNpmGlobalPrefixLayoutFromPrefix } from "./update-global.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+//#region src/infra/package-update-steps.ts
+function formatError(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+async function pathExists(targetPath) {
+	try {
+		await fs.access(targetPath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+async function readPackageVersionIfPresent(packageRoot) {
+	if (!packageRoot) return null;
+	try {
+		return await readPackageVersion(packageRoot);
+	} catch {
+		return null;
+	}
+}
+async function createStagedNpmInstall(installTarget, packageName) {
+	if (installTarget.manager !== "npm") return null;
+	const targetLayout = resolveNpmGlobalPrefixLayoutFromGlobalRoot(installTarget.globalRoot);
+	if (!targetLayout) return null;
+	await fs.mkdir(targetLayout.globalRoot, { recursive: true });
+	const prefix = await fs.mkdtemp(path.join(targetLayout.globalRoot, ".xopc-update-stage-"));
+	const layout = resolveNpmGlobalPrefixLayoutFromPrefix(prefix);
+	return {
+		prefix,
+		layout,
+		packageRoot: path.join(layout.globalRoot, packageName)
+	};
+}
+async function prepareStagedNpmInstall(installTarget, packageName) {
+	const startedAt = Date.now();
+	try {
+		return {
+			stagedInstall: await createStagedNpmInstall(installTarget, packageName),
+			failedStep: null
+		};
+	} catch (err) {
+		return {
+			stagedInstall: null,
+			failedStep: {
+				name: "global install stage",
+				command: "prepare staged npm install",
+				cwd: (installTarget.manager === "npm" ? resolveNpmGlobalPrefixLayoutFromGlobalRoot(installTarget.globalRoot) : null)?.prefix ?? installTarget.globalRoot ?? process.cwd(),
+				durationMs: Date.now() - startedAt,
+				exitCode: 1,
+				stdoutTail: null,
+				stderrTail: formatError(err)
+			}
+		};
+	}
+}
+async function cleanupStagedNpmInstall(stage) {
+	if (!stage) return;
+	await fs.rm(stage.prefix, {
+		recursive: true,
+		force: true
+	}).catch(() => void 0);
+}
+async function copyPathEntry(source, destination) {
+	const stat = await fs.lstat(source);
+	await fs.rm(destination, {
+		recursive: true,
+		force: true
+	}).catch(() => void 0);
+	if (stat.isSymbolicLink()) {
+		await fs.symlink(await fs.readlink(source), destination);
+		return;
+	}
+	if (stat.isDirectory()) {
+		await fs.cp(source, destination, {
+			recursive: true,
+			force: true,
+			preserveTimestamps: false
+		});
+		return;
+	}
+	await fs.copyFile(source, destination);
+	await fs.chmod(destination, stat.mode).catch(() => void 0);
+}
+async function replaceNpmBinShims(params) {
+	let entries = [];
+	try {
+		entries = await fs.readdir(params.stageLayout.binDir);
+	} catch {
+		return;
+	}
+	const names = new Set([params.packageName, "xopc"]);
+	const shimEntries = entries.filter((entry) => {
+		const parsed = path.parse(entry);
+		return names.has(entry) || names.has(parsed.name);
+	});
+	if (shimEntries.length === 0) return;
+	const backup = {
+		backupDir: await fs.mkdtemp(path.join(params.targetLayout.globalRoot, ".xopc-shim-backup-")),
+		targetBinDir: params.targetLayout.binDir,
+		entries: []
+	};
+	try {
+		await fs.mkdir(params.targetLayout.binDir, { recursive: true });
+		for (const entry of shimEntries) {
+			const destination = path.join(params.targetLayout.binDir, entry);
+			const hadExisting = await pathExists(destination);
+			backup.entries.push({
+				name: entry,
+				hadExisting
+			});
+			if (hadExisting) await copyPathEntry(destination, path.join(backup.backupDir, entry));
+		}
+		for (const entry of shimEntries) await copyPathEntry(path.join(params.stageLayout.binDir, entry), path.join(params.targetLayout.binDir, entry));
+	} catch (err) {
+		await restoreNpmBinShimBackup(backup);
+		throw err;
+	} finally {
+		await fs.rm(backup.backupDir, {
+			recursive: true,
+			force: true
+		}).catch(() => void 0);
+	}
+}
+async function restoreNpmBinShimBackup(backup) {
+	await fs.mkdir(backup.targetBinDir, { recursive: true });
+	for (const entry of backup.entries) {
+		const destination = path.join(backup.targetBinDir, entry.name);
+		await fs.rm(destination, {
+			recursive: true,
+			force: true
+		}).catch(() => void 0);
+		if (entry.hadExisting) await copyPathEntry(path.join(backup.backupDir, entry.name), destination);
+	}
+}
+async function swapStagedNpmInstall(params) {
+	const startedAt = Date.now();
+	const targetLayout = resolveNpmGlobalPrefixLayoutFromGlobalRoot(params.installTarget.globalRoot);
+	const targetPackageRoot = params.installTarget.packageRoot;
+	if (!targetLayout || !targetPackageRoot) return {
+		name: "global install swap",
+		command: "swap staged npm install",
+		cwd: params.stage.prefix,
+		durationMs: Date.now() - startedAt,
+		exitCode: 1,
+		stdoutTail: null,
+		stderrTail: "cannot resolve npm global prefix layout"
+	};
+	const backupRoot = path.join(targetLayout.globalRoot, `.xopc-${process.pid}-${Date.now()}`);
+	let movedExisting = false;
+	let movedStaged = false;
+	try {
+		await fs.mkdir(targetLayout.globalRoot, { recursive: true });
+		if (await pathExists(targetPackageRoot)) {
+			await fs.rename(targetPackageRoot, backupRoot);
+			movedExisting = true;
+		}
+		await fs.rename(params.stage.packageRoot, targetPackageRoot);
+		movedStaged = true;
+		await replaceNpmBinShims({
+			stageLayout: params.stage.layout,
+			targetLayout,
+			packageName: params.packageName
+		});
+		if (movedExisting) await fs.rm(backupRoot, {
+			recursive: true,
+			force: true
+		});
+		return {
+			name: "global install swap",
+			command: `swap ${params.stage.packageRoot} -> ${targetPackageRoot}`,
+			cwd: targetLayout.globalRoot,
+			durationMs: Date.now() - startedAt,
+			exitCode: 0,
+			stdoutTail: movedExisting ? `replaced ${params.packageName}` : `installed ${params.packageName}`,
+			stderrTail: null
+		};
+	} catch (err) {
+		if (movedStaged) await fs.rm(targetPackageRoot, {
+			recursive: true,
+			force: true
+		}).catch(() => void 0);
+		if (movedExisting) await fs.rename(backupRoot, targetPackageRoot).catch(() => void 0);
+		return {
+			name: "global install swap",
+			command: `swap ${params.stage.packageRoot} -> ${targetPackageRoot}`,
+			cwd: targetLayout.globalRoot,
+			durationMs: Date.now() - startedAt,
+			exitCode: 1,
+			stdoutTail: null,
+			stderrTail: formatError(err)
+		};
+	}
+}
+async function runGlobalPackageUpdateSteps(params) {
+	const installCwd = params.installCwd === void 0 ? {} : { cwd: params.installCwd };
+	const installEnv = params.env === void 0 ? {} : { env: params.env };
+	let stagedInstall = null;
+	try {
+		const preparedInstall = await prepareStagedNpmInstall(params.installTarget, params.packageName);
+		stagedInstall = preparedInstall.stagedInstall;
+		if (preparedInstall.failedStep) return {
+			steps: [preparedInstall.failedStep],
+			verifiedPackageRoot: params.packageRoot ?? null,
+			afterVersion: null,
+			failedStep: preparedInstall.failedStep
+		};
+		const updateStep = await params.runStep({
+			name: "global update",
+			argv: globalInstallArgs(params.installTarget, params.installSpec, params.packageRoot, stagedInstall?.prefix),
+			...installCwd,
+			...installEnv,
+			timeoutMs: params.timeoutMs
+		});
+		const steps = [updateStep];
+		let finalInstallStep = updateStep;
+		if (updateStep.exitCode !== 0) {
+			await cleanupStagedNpmInstall(stagedInstall);
+			stagedInstall = null;
+			const preparedFallbackInstall = await prepareStagedNpmInstall(params.installTarget, params.packageName);
+			stagedInstall = preparedFallbackInstall.stagedInstall;
+			if (preparedFallbackInstall.failedStep) {
+				steps.push(preparedFallbackInstall.failedStep);
+				return {
+					steps,
+					verifiedPackageRoot: params.packageRoot ?? null,
+					afterVersion: null,
+					failedStep: preparedFallbackInstall.failedStep
+				};
+			}
+			const fallbackArgv = globalInstallFallbackArgs(params.installTarget, params.installSpec, params.packageRoot, stagedInstall?.prefix);
+			if (fallbackArgv) {
+				const fallbackStep = await params.runStep({
+					name: "global update (omit optional)",
+					argv: fallbackArgv,
+					...installCwd,
+					...installEnv,
+					timeoutMs: params.timeoutMs
+				});
+				steps.push(fallbackStep);
+				finalInstallStep = fallbackStep;
+			} else {
+				await cleanupStagedNpmInstall(stagedInstall);
+				stagedInstall = null;
+			}
+		}
+		const livePackageRoot = params.installTarget.packageRoot ?? params.packageRoot ?? (await resolveGlobalInstallTarget({
+			manager: params.installTarget,
+			runCommand: params.runCommand,
+			timeoutMs: params.timeoutMs,
+			pkgRoot: params.packageRoot
+		})).packageRoot ?? null;
+		const verificationPackageRoot = stagedInstall?.packageRoot ?? livePackageRoot;
+		let verifiedPackageRoot = livePackageRoot ?? verificationPackageRoot;
+		let afterVersion = null;
+		if (finalInstallStep.exitCode === 0 && verificationPackageRoot) {
+			const candidateVersion = await readPackageVersion(verificationPackageRoot);
+			if (!stagedInstall) afterVersion = candidateVersion;
+			const verificationErrors = await collectInstalledGlobalPackageErrors({
+				packageRoot: verificationPackageRoot,
+				expectedVersion: resolveExpectedInstalledVersionFromSpec(params.installSpec)
+			});
+			if (verificationErrors.length > 0) steps.push({
+				name: "global install verify",
+				command: `verify ${verificationPackageRoot}`,
+				cwd: verificationPackageRoot,
+				durationMs: 0,
+				exitCode: 1,
+				stderrTail: verificationErrors.join("\n"),
+				stdoutTail: null
+			});
+			if (stagedInstall && verificationErrors.length === 0) {
+				const swapStep = await swapStagedNpmInstall({
+					stage: stagedInstall,
+					installTarget: params.installTarget,
+					packageName: params.packageName
+				});
+				steps.push(swapStep);
+				if (swapStep.exitCode === 0) {
+					verifiedPackageRoot = params.installTarget.packageRoot ?? verifiedPackageRoot;
+					afterVersion = candidateVersion;
+				}
+			}
+		}
+		if (steps.find((step) => (step.name === "global install verify" || step.name === "global install swap") && step.exitCode !== 0) && stagedInstall) afterVersion = await readPackageVersionIfPresent(livePackageRoot);
+		const failedStep = finalInstallStep.exitCode !== 0 ? finalInstallStep : steps.find((step) => step !== updateStep && step.exitCode !== 0) ?? null;
+		return {
+			steps,
+			verifiedPackageRoot,
+			afterVersion,
+			failedStep
+		};
+	} finally {
+		await cleanupStagedNpmInstall(stagedInstall);
+	}
+}
+const DEFAULT_PACKAGE_NAME = XOPC_PACKAGE_NAME;
+//#endregion
+export { DEFAULT_PACKAGE_NAME, runGlobalPackageUpdateSteps };
+
+//# sourceMappingURL=package-update-steps.js.map

package/dist/src/infra/package-update-steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-update-steps.js","names":[],"sources":["../../../src/infra/package-update-steps.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\n\nimport { readPackageVersion } from './package-json.js';\nimport type { CommandRunner } from './run-command.js';\nimport {\n  collectInstalledGlobalPackageErrors,\n  globalInstallArgs,\n  globalInstallFallbackArgs,\n  resolveNpmGlobalPrefixLayoutFromGlobalRoot,\n  resolveNpmGlobalPrefixLayoutFromPrefix,\n  resolveExpectedInstalledVersionFromSpec,\n  resolveGlobalInstallTarget,\n  XOPC_PACKAGE_NAME,\n  type NpmGlobalPrefixLayout,\n  type ResolvedGlobalInstallTarget,\n} from './update-global.js';\n\nexport type PackageUpdateStepResult = {\n  name: string;\n  command: string;\n  cwd: string;\n  durationMs: number;\n  exitCode: number | null;\n  stdoutTail?: string | null;\n  stderrTail?: string | null;\n};\n\nexport type PackageUpdateStepRunner = (params: {\n  name: string;\n  argv: string[];\n  cwd?: string;\n  timeoutMs: number;\n  env?: NodeJS.ProcessEnv;\n}) => Promise<PackageUpdateStepResult>;\n\ntype StagedNpmInstall = {\n  prefix: string;\n  layout: NpmGlobalPrefixLayout;\n  packageRoot: string;\n};\n\ntype NpmBinShimBackup = {\n  backupDir: string;\n  targetBinDir: string;\n  entries: Array<{ name: string; hadExisting: boolean }>;\n};\n\nfunction formatError(err: unknown): string {\n  return err instanceof Error ? err.message : String(err);\n}\n\nasync function pathExists(targetPath: string): Promise<boolean> {\n  try {\n    await fs.access(targetPath);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nasync function readPackageVersionIfPresent(packageRoot: string | null): Promise<string | null> {\n  if (!packageRoot) return null;\n  try {\n    return await readPackageVersion(packageRoot);\n  } catch {\n    return null;\n  }\n}\n\nasync function createStagedNpmInstall(\n  installTarget: ResolvedGlobalInstallTarget,\n  packageName: string,\n): Promise<StagedNpmInstall | null> {\n  if (installTarget.manager !== 'npm') return null;\n  const targetLayout = resolveNpmGlobalPrefixLayoutFromGlobalRoot(installTarget.globalRoot);\n  if (!targetLayout) return null;\n  await fs.mkdir(targetLayout.globalRoot, { recursive: true });\n  const prefix = await fs.mkdtemp(path.join(targetLayout.globalRoot, '.xopc-update-stage-'));\n  const layout = resolveNpmGlobalPrefixLayoutFromPrefix(prefix);\n  return {\n    prefix,\n    layout,\n    packageRoot: path.join(layout.globalRoot, packageName),\n  };\n}\n\nasync function prepareStagedNpmInstall(\n  installTarget: ResolvedGlobalInstallTarget,\n  packageName: string,\n): Promise<{ stagedInstall: StagedNpmInstall | null; failedStep: PackageUpdateStepResult | null }> {\n  const startedAt = Date.now();\n  try {\n    return { stagedInstall: await createStagedNpmInstall(installTarget, packageName), failedStep: null };\n  } catch (err) {\n    const targetLayout =\n      installTarget.manager === 'npm'\n        ? resolveNpmGlobalPrefixLayoutFromGlobalRoot(installTarget.globalRoot)\n        : null;\n    return {\n      stagedInstall: null,\n      failedStep: {\n        name: 'global install stage',\n        command: 'prepare staged npm install',\n        cwd: targetLayout?.prefix ?? installTarget.globalRoot ?? process.cwd(),\n        durationMs: Date.now() - startedAt,\n        exitCode: 1,\n        stdoutTail: null,\n        stderrTail: formatError(err),\n      },\n    };\n  }\n}\n\nasync function cleanupStagedNpmInstall(stage: StagedNpmInstall | null): Promise<void> {\n  if (!stage) return;\n  await fs.rm(stage.prefix, { recursive: true, force: true }).catch(() => undefined);\n}\n\nasync function copyPathEntry(source: string, destination: string): Promise<void> {\n  const stat = await fs.lstat(source);\n  await fs.rm(destination, { recursive: true, force: true }).catch(() => undefined);\n  if (stat.isSymbolicLink()) {\n    await fs.symlink(await fs.readlink(source), destination);\n    return;\n  }\n  if (stat.isDirectory()) {\n    await fs.cp(source, destination, { recursive: true, force: true, preserveTimestamps: false });\n    return;\n  }\n  await fs.copyFile(source, destination);\n  await fs.chmod(destination, stat.mode).catch(() => undefined);\n}\n\nasync function replaceNpmBinShims(params: {\n  stageLayout: NpmGlobalPrefixLayout;\n  targetLayout: NpmGlobalPrefixLayout;\n  packageName: string;\n}): Promise<void> {\n  let entries: string[] = [];\n  try {\n    entries = await fs.readdir(params.stageLayout.binDir);\n  } catch {\n    return;\n  }\n\n  const names = new Set([params.packageName, 'xopc']);\n  const shimEntries = entries.filter((entry) => {\n    const parsed = path.parse(entry);\n    return names.has(entry) || names.has(parsed.name);\n  });\n  if (shimEntries.length === 0) return;\n\n  const backup: NpmBinShimBackup = {\n    backupDir: await fs.mkdtemp(path.join(params.targetLayout.globalRoot, '.xopc-shim-backup-')),\n    targetBinDir: params.targetLayout.binDir,\n    entries: [],\n  };\n\n  try {\n    await fs.mkdir(params.targetLayout.binDir, { recursive: true });\n    for (const entry of shimEntries) {\n      const destination = path.join(params.targetLayout.binDir, entry);\n      const hadExisting = await pathExists(destination);\n      backup.entries.push({ name: entry, hadExisting });\n      if (hadExisting) {\n        await copyPathEntry(destination, path.join(backup.backupDir, entry));\n      }\n    }\n    for (const entry of shimEntries) {\n      await copyPathEntry(\n        path.join(params.stageLayout.binDir, entry),\n        path.join(params.targetLayout.binDir, entry),\n      );\n    }\n  } catch (err) {\n    await restoreNpmBinShimBackup(backup);\n    throw err;\n  } finally {\n    await fs.rm(backup.backupDir, { recursive: true, force: true }).catch(() => undefined);\n  }\n}\n\nasync function restoreNpmBinShimBackup(backup: NpmBinShimBackup): Promise<void> {\n  await fs.mkdir(backup.targetBinDir, { recursive: true });\n  for (const entry of backup.entries) {\n    const destination = path.join(backup.targetBinDir, entry.name);\n    await fs.rm(destination, { recursive: true, force: true }).catch(() => undefined);\n    if (entry.hadExisting) {\n      await copyPathEntry(path.join(backup.backupDir, entry.name), destination);\n    }\n  }\n}\n\nasync function swapStagedNpmInstall(params: {\n  stage: StagedNpmInstall;\n  installTarget: ResolvedGlobalInstallTarget;\n  packageName: string;\n}): Promise<PackageUpdateStepResult> {\n  const startedAt = Date.now();\n  const targetLayout = resolveNpmGlobalPrefixLayoutFromGlobalRoot(params.installTarget.globalRoot);\n  const targetPackageRoot = params.installTarget.packageRoot;\n  if (!targetLayout || !targetPackageRoot) {\n    return {\n      name: 'global install swap',\n      command: 'swap staged npm install',\n      cwd: params.stage.prefix,\n      durationMs: Date.now() - startedAt,\n      exitCode: 1,\n      stdoutTail: null,\n      stderrTail: 'cannot resolve npm global prefix layout',\n    };\n  }\n\n  const backupRoot = path.join(targetLayout.globalRoot, `.xopc-${process.pid}-${Date.now()}`);\n  let movedExisting = false;\n  let movedStaged = false;\n  try {\n    await fs.mkdir(targetLayout.globalRoot, { recursive: true });\n    if (await pathExists(targetPackageRoot)) {\n      await fs.rename(targetPackageRoot, backupRoot);\n      movedExisting = true;\n    }\n    await fs.rename(params.stage.packageRoot, targetPackageRoot);\n    movedStaged = true;\n    await replaceNpmBinShims({\n      stageLayout: params.stage.layout,\n      targetLayout,\n      packageName: params.packageName,\n    });\n    if (movedExisting) {\n      await fs.rm(backupRoot, { recursive: true, force: true });\n    }\n    return {\n      name: 'global install swap',\n      command: `swap ${params.stage.packageRoot} -> ${targetPackageRoot}`,\n      cwd: targetLayout.globalRoot,\n      durationMs: Date.now() - startedAt,\n      exitCode: 0,\n      stdoutTail: movedExisting ? `replaced ${params.packageName}` : `installed ${params.packageName}`,\n      stderrTail: null,\n    };\n  } catch (err) {\n    if (movedStaged) {\n      await fs.rm(targetPackageRoot, { recursive: true, force: true }).catch(() => undefined);\n    }\n    if (movedExisting) {\n      await fs.rename(backupRoot, targetPackageRoot).catch(() => undefined);\n    }\n    return {\n      name: 'global install swap',\n      command: `swap ${params.stage.packageRoot} -> ${targetPackageRoot}`,\n      cwd: targetLayout.globalRoot,\n      durationMs: Date.now() - startedAt,\n      exitCode: 1,\n      stdoutTail: null,\n      stderrTail: formatError(err),\n    };\n  }\n}\n\nexport async function runGlobalPackageUpdateSteps(params: {\n  installTarget: ResolvedGlobalInstallTarget;\n  installSpec: string;\n  packageName: string;\n  packageRoot?: string | null;\n  runCommand: CommandRunner;\n  runStep: PackageUpdateStepRunner;\n  timeoutMs: number;\n  env?: NodeJS.ProcessEnv;\n  installCwd?: string;\n}): Promise<{\n  steps: PackageUpdateStepResult[];\n  verifiedPackageRoot: string | null;\n  afterVersion: string | null;\n  failedStep: PackageUpdateStepResult | null;\n}> {\n  const installCwd = params.installCwd === undefined ? {} : { cwd: params.installCwd };\n  const installEnv = params.env === undefined ? {} : { env: params.env };\n  let stagedInstall: StagedNpmInstall | null = null;\n\n  try {\n    const preparedInstall = await prepareStagedNpmInstall(params.installTarget, params.packageName);\n    stagedInstall = preparedInstall.stagedInstall;\n    if (preparedInstall.failedStep) {\n      return {\n        steps: [preparedInstall.failedStep],\n        verifiedPackageRoot: params.packageRoot ?? null,\n        afterVersion: null,\n        failedStep: preparedInstall.failedStep,\n      };\n    }\n\n    const updateStep = await params.runStep({\n      name: 'global update',\n      argv: globalInstallArgs(\n        params.installTarget,\n        params.installSpec,\n        params.packageRoot,\n        stagedInstall?.prefix,\n      ),\n      ...installCwd,\n      ...installEnv,\n      timeoutMs: params.timeoutMs,\n    });\n\n    const steps = [updateStep];\n    let finalInstallStep = updateStep;\n    if (updateStep.exitCode !== 0) {\n      await cleanupStagedNpmInstall(stagedInstall);\n      stagedInstall = null;\n      const preparedFallbackInstall = await prepareStagedNpmInstall(\n        params.installTarget,\n        params.packageName,\n      );\n      stagedInstall = preparedFallbackInstall.stagedInstall;\n      if (preparedFallbackInstall.failedStep) {\n        steps.push(preparedFallbackInstall.failedStep);\n        return {\n          steps,\n          verifiedPackageRoot: params.packageRoot ?? null,\n          afterVersion: null,\n          failedStep: preparedFallbackInstall.failedStep,\n        };\n      }\n\n      const fallbackArgv = globalInstallFallbackArgs(\n        params.installTarget,\n        params.installSpec,\n        params.packageRoot,\n        stagedInstall?.prefix,\n      );\n      if (fallbackArgv) {\n        const fallbackStep = await params.runStep({\n          name: 'global update (omit optional)',\n          argv: fallbackArgv,\n          ...installCwd,\n          ...installEnv,\n          timeoutMs: params.timeoutMs,\n        });\n        steps.push(fallbackStep);\n        finalInstallStep = fallbackStep;\n      } else {\n        await cleanupStagedNpmInstall(stagedInstall);\n        stagedInstall = null;\n      }\n    }\n\n    const livePackageRoot =\n      params.installTarget.packageRoot ??\n      params.packageRoot ??\n      (\n        await resolveGlobalInstallTarget({\n          manager: params.installTarget,\n          runCommand: params.runCommand,\n          timeoutMs: params.timeoutMs,\n          pkgRoot: params.packageRoot,\n        })\n      ).packageRoot ??\n      null;\n    const verificationPackageRoot = stagedInstall?.packageRoot ?? livePackageRoot;\n    let verifiedPackageRoot = livePackageRoot ?? verificationPackageRoot;\n\n    let afterVersion: string | null = null;\n    if (finalInstallStep.exitCode === 0 && verificationPackageRoot) {\n      const candidateVersion = await readPackageVersion(verificationPackageRoot);\n      if (!stagedInstall) {\n        afterVersion = candidateVersion;\n      }\n      const expectedVersion = resolveExpectedInstalledVersionFromSpec(params.installSpec);\n      const verificationErrors = await collectInstalledGlobalPackageErrors({\n        packageRoot: verificationPackageRoot,\n        expectedVersion,\n      });\n      if (verificationErrors.length > 0) {\n        steps.push({\n          name: 'global install verify',\n          command: `verify ${verificationPackageRoot}`,\n          cwd: verificationPackageRoot,\n          durationMs: 0,\n          exitCode: 1,\n          stderrTail: verificationErrors.join('\\n'),\n          stdoutTail: null,\n        });\n      }\n\n      if (stagedInstall && verificationErrors.length === 0) {\n        const swapStep = await swapStagedNpmInstall({\n          stage: stagedInstall,\n          installTarget: params.installTarget,\n          packageName: params.packageName,\n        });\n        steps.push(swapStep);\n        if (swapStep.exitCode === 0) {\n          verifiedPackageRoot = params.installTarget.packageRoot ?? verifiedPackageRoot;\n          afterVersion = candidateVersion;\n        }\n      }\n    }\n\n    const failedVerifyOrSwap = steps.find(\n      (step) =>\n        (step.name === 'global install verify' || step.name === 'global install swap') &&\n        step.exitCode !== 0,\n    );\n    if (failedVerifyOrSwap && stagedInstall) {\n      afterVersion = await readPackageVersionIfPresent(livePackageRoot);\n    }\n\n    const failedStep =\n      finalInstallStep.exitCode !== 0\n        ? finalInstallStep\n        : (steps.find((step) => step !== updateStep && step.exitCode !== 0) ?? null);\n\n    return { steps, verifiedPackageRoot, afterVersion, failedStep };\n  } finally {\n    await cleanupStagedNpmInstall(stagedInstall);\n  }\n}\n\nexport const DEFAULT_PACKAGE_NAME = XOPC_PACKAGE_NAME;\n"],"mappings":"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"}

package/dist/src/infra/path-env.d.ts

@@ -0,0 +1,11 @@
+type EnsureXopcPathOpts = {
+    execPath?: string;
+    cwd?: string;
+    homeDir?: string;
+    platform?: NodeJS.Platform;
+    pathEnv?: string;
+};
+/** Bootstrap PATH for launchd/daemon environments (npm/pnpm/git subprocesses). */
+export declare function ensureXopcCliOnPath(opts?: EnsureXopcPathOpts): void;
+export declare function resolveExecPathBinPrepend(): string[];
+export {};

package/dist/src/infra/path-env.js

@@ -0,0 +1,90 @@
+import { resolveBrewPathDirs } from "./brew.js";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+//#region src/infra/path-env.ts
+function isTruthyEnvValue(value) {
+	if (!value) return false;
+	const normalized = value.trim().toLowerCase();
+	return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+function isExecutable(filePath) {
+	try {
+		fs.accessSync(filePath, fs.constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function isDirectory(dirPath) {
+	try {
+		return fs.statSync(dirPath).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function mergePath(params) {
+	const partsExisting = params.existing.split(path.delimiter).map((part) => part.trim()).filter(Boolean);
+	const partsPrepend = (params.prepend ?? []).map((part) => part.trim()).filter(Boolean);
+	const partsAppend = (params.append ?? []).map((part) => part.trim()).filter(Boolean);
+	const seen = /* @__PURE__ */ new Set();
+	const merged = [];
+	for (const part of [
+		...partsPrepend,
+		...partsExisting,
+		...partsAppend
+	]) {
+		if (seen.has(part)) continue;
+		seen.add(part);
+		merged.push(part);
+	}
+	return merged.join(path.delimiter);
+}
+function candidateBinDirs(opts) {
+	const execPath = opts.execPath ?? process.execPath;
+	const homeDir = opts.homeDir ?? os.homedir();
+	const platform = opts.platform ?? process.platform;
+	const prepend = [];
+	const append = [];
+	try {
+		const execDir = path.dirname(execPath);
+		if (isExecutable(execPath)) prepend.push(execDir);
+	} catch {}
+	try {
+		const execDir = path.dirname(execPath);
+		if (isExecutable(path.join(execDir, "xopc"))) prepend.push(execDir);
+	} catch {}
+	prepend.push("/usr/bin", "/bin");
+	append.push(...resolveBrewPathDirs({ homeDir }));
+	if (platform === "darwin") append.push(path.join(homeDir, "Library", "pnpm"));
+	if (process.env.XDG_BIN_HOME) append.push(process.env.XDG_BIN_HOME);
+	append.push(path.join(homeDir, ".local", "bin"), path.join(homeDir, ".local", "share", "pnpm"), path.join(homeDir, ".bun", "bin"), path.join(homeDir, ".nvm", "versions", "node"));
+	return {
+		prepend: prepend.filter(isDirectory),
+		append: append.filter(isDirectory)
+	};
+}
+/** Bootstrap PATH for launchd/daemon environments (npm/pnpm/git subprocesses). */
+function ensureXopcCliOnPath(opts = {}) {
+	if (isTruthyEnvValue(process.env.XOPC_PATH_BOOTSTRAPPED)) return;
+	process.env.XOPC_PATH_BOOTSTRAPPED = "1";
+	const existing = opts.pathEnv ?? process.env.PATH ?? "";
+	const { prepend, append } = candidateBinDirs(opts);
+	if (prepend.length === 0 && append.length === 0) return;
+	const merged = mergePath({
+		existing,
+		prepend,
+		append
+	});
+	if (merged) process.env.PATH = merged;
+}
+function resolveExecPathBinPrepend() {
+	const execPath = process.execPath?.trim();
+	if (!execPath) return [];
+	const execDir = path.dirname(execPath);
+	return isDirectory(execDir) ? [execDir] : [];
+}
+//#endregion
+export { ensureXopcCliOnPath, resolveExecPathBinPrepend };
+
+//# sourceMappingURL=path-env.js.map

package/dist/src/infra/path-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-env.js","names":[],"sources":["../../../src/infra/path-env.ts"],"sourcesContent":["import fs from 'node:fs';\nimport os from 'node:os';\nimport path from 'node:path';\n\nimport { resolveBrewPathDirs } from './brew.js';\n\ntype EnsureXopcPathOpts = {\n  execPath?: string;\n  cwd?: string;\n  homeDir?: string;\n  platform?: NodeJS.Platform;\n  pathEnv?: string;\n};\n\nfunction isTruthyEnvValue(value: string | undefined): boolean {\n  if (!value) return false;\n  const normalized = value.trim().toLowerCase();\n  return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';\n}\n\nfunction isExecutable(filePath: string): boolean {\n  try {\n    fs.accessSync(filePath, fs.constants.X_OK);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nfunction isDirectory(dirPath: string): boolean {\n  try {\n    return fs.statSync(dirPath).isDirectory();\n  } catch {\n    return false;\n  }\n}\n\nfunction mergePath(params: { existing: string; prepend?: string[]; append?: string[] }): string {\n  const partsExisting = params.existing\n    .split(path.delimiter)\n    .map((part) => part.trim())\n    .filter(Boolean);\n  const partsPrepend = (params.prepend ?? []).map((part) => part.trim()).filter(Boolean);\n  const partsAppend = (params.append ?? []).map((part) => part.trim()).filter(Boolean);\n  const seen = new Set<string>();\n  const merged: string[] = [];\n  for (const part of [...partsPrepend, ...partsExisting, ...partsAppend]) {\n    if (seen.has(part)) continue;\n    seen.add(part);\n    merged.push(part);\n  }\n  return merged.join(path.delimiter);\n}\n\nfunction candidateBinDirs(opts: EnsureXopcPathOpts): { prepend: string[]; append: string[] } {\n  const execPath = opts.execPath ?? process.execPath;\n  const homeDir = opts.homeDir ?? os.homedir();\n  const platform = opts.platform ?? process.platform;\n  const prepend: string[] = [];\n  const append: string[] = [];\n\n  try {\n    const execDir = path.dirname(execPath);\n    if (isExecutable(execPath)) prepend.push(execDir);\n  } catch {\n    // ignore\n  }\n\n  try {\n    const execDir = path.dirname(execPath);\n    const siblingCli = path.join(execDir, 'xopc');\n    if (isExecutable(siblingCli)) prepend.push(execDir);\n  } catch {\n    // ignore\n  }\n\n  prepend.push('/usr/bin', '/bin');\n  append.push(...resolveBrewPathDirs({ homeDir }));\n  if (platform === 'darwin') append.push(path.join(homeDir, 'Library', 'pnpm'));\n  if (process.env.XDG_BIN_HOME) append.push(process.env.XDG_BIN_HOME);\n  append.push(\n    path.join(homeDir, '.local', 'bin'),\n    path.join(homeDir, '.local', 'share', 'pnpm'),\n    path.join(homeDir, '.bun', 'bin'),\n    path.join(homeDir, '.nvm', 'versions', 'node'),\n  );\n\n  return { prepend: prepend.filter(isDirectory), append: append.filter(isDirectory) };\n}\n\n/** Bootstrap PATH for launchd/daemon environments (npm/pnpm/git subprocesses). */\nexport function ensureXopcCliOnPath(opts: EnsureXopcPathOpts = {}): void {\n  if (isTruthyEnvValue(process.env.XOPC_PATH_BOOTSTRAPPED)) return;\n  process.env.XOPC_PATH_BOOTSTRAPPED = '1';\n\n  const existing = opts.pathEnv ?? process.env.PATH ?? '';\n  const { prepend, append } = candidateBinDirs(opts);\n  if (prepend.length === 0 && append.length === 0) return;\n\n  const merged = mergePath({ existing, prepend, append });\n  if (merged) process.env.PATH = merged;\n}\n\nexport function resolveExecPathBinPrepend(): string[] {\n  const execPath = process.execPath?.trim();\n  if (!execPath) return [];\n  const execDir = path.dirname(execPath);\n  return isDirectory(execDir) ? [execDir] : [];\n}\n"],"mappings":"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"}

package/dist/src/infra/path-prepend.d.ts

@@ -0,0 +1,7 @@
+/** Find the actual key used for PATH (Windows may use `Path`). */
+export declare function findPathKey(env: Record<string, string>): string;
+export declare function normalizePathPrepend(entries?: string[]): string[];
+export declare function mergePathPrepend(existing: string | undefined, prepend: string[]): string;
+export declare function applyPathPrepend(env: Record<string, string>, prepend: string[] | undefined, options?: {
+    requireExisting?: boolean;
+}): void;

package/dist/src/infra/path-prepend.js

@@ -0,0 +1,44 @@
+import path from "node:path";
+//#region src/infra/path-prepend.ts
+/** Find the actual key used for PATH (Windows may use `Path`). */
+function findPathKey(env) {
+	if ("PATH" in env) return "PATH";
+	for (const key of Object.keys(env)) if (key.toUpperCase() === "PATH") return key;
+	return "PATH";
+}
+function normalizePathPrepend(entries) {
+	if (!Array.isArray(entries)) return [];
+	const seen = /* @__PURE__ */ new Set();
+	const normalized = [];
+	for (const entry of entries) {
+		if (typeof entry !== "string") continue;
+		const trimmed = entry.trim();
+		if (!trimmed || seen.has(trimmed)) continue;
+		seen.add(trimmed);
+		normalized.push(trimmed);
+	}
+	return normalized;
+}
+function mergePathPrepend(existing, prepend) {
+	if (prepend.length === 0) return existing ?? "";
+	const partsExisting = (existing ?? "").split(path.delimiter).map((part) => part.trim()).filter(Boolean);
+	const merged = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const part of [...prepend, ...partsExisting]) {
+		if (seen.has(part)) continue;
+		seen.add(part);
+		merged.push(part);
+	}
+	return merged.join(path.delimiter);
+}
+function applyPathPrepend(env, prepend, options) {
+	if (!Array.isArray(prepend) || prepend.length === 0) return;
+	const pathKey = findPathKey(env);
+	if (options?.requireExisting && !env[pathKey]) return;
+	const merged = mergePathPrepend(env[pathKey], prepend);
+	if (merged) env[pathKey] = merged;
+}
+//#endregion
+export { applyPathPrepend, findPathKey, mergePathPrepend, normalizePathPrepend };
+
+//# sourceMappingURL=path-prepend.js.map

package/dist/src/infra/path-prepend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-prepend.js","names":[],"sources":["../../../src/infra/path-prepend.ts"],"sourcesContent":["import path from 'node:path';\n\n/** Find the actual key used for PATH (Windows may use `Path`). */\nexport function findPathKey(env: Record<string, string>): string {\n  if ('PATH' in env) return 'PATH';\n  for (const key of Object.keys(env)) {\n    if (key.toUpperCase() === 'PATH') return key;\n  }\n  return 'PATH';\n}\n\nexport function normalizePathPrepend(entries?: string[]): string[] {\n  if (!Array.isArray(entries)) return [];\n  const seen = new Set<string>();\n  const normalized: string[] = [];\n  for (const entry of entries) {\n    if (typeof entry !== 'string') continue;\n    const trimmed = entry.trim();\n    if (!trimmed || seen.has(trimmed)) continue;\n    seen.add(trimmed);\n    normalized.push(trimmed);\n  }\n  return normalized;\n}\n\nexport function mergePathPrepend(existing: string | undefined, prepend: string[]): string {\n  if (prepend.length === 0) return existing ?? '';\n  const partsExisting = (existing ?? '')\n    .split(path.delimiter)\n    .map((part) => part.trim())\n    .filter(Boolean);\n  const merged: string[] = [];\n  const seen = new Set<string>();\n  for (const part of [...prepend, ...partsExisting]) {\n    if (seen.has(part)) continue;\n    seen.add(part);\n    merged.push(part);\n  }\n  return merged.join(path.delimiter);\n}\n\nexport function applyPathPrepend(\n  env: Record<string, string>,\n  prepend: string[] | undefined,\n  options?: { requireExisting?: boolean },\n): void {\n  if (!Array.isArray(prepend) || prepend.length === 0) return;\n  const pathKey = findPathKey(env);\n  if (options?.requireExisting && !env[pathKey]) return;\n  const merged = mergePathPrepend(env[pathKey], prepend);\n  if (merged) env[pathKey] = merged;\n}\n"],"mappings":";;;AAGA,SAAgB,YAAY,KAAqC;AAC/D,KAAI,UAAU,IAAK,QAAO;AAC1B,MAAK,MAAM,OAAO,OAAO,KAAK,IAAI,CAChC,KAAI,IAAI,aAAa,KAAK,OAAQ,QAAO;AAE3C,QAAO;;AAGT,SAAgB,qBAAqB,SAA8B;AACjE,KAAI,CAAC,MAAM,QAAQ,QAAQ,CAAE,QAAO,EAAE;CACtC,MAAM,uBAAO,IAAI,KAAa;CAC9B,MAAM,aAAuB,EAAE;AAC/B,MAAK,MAAM,SAAS,SAAS;AAC3B,MAAI,OAAO,UAAU,SAAU;EAC/B,MAAM,UAAU,MAAM,MAAM;AAC5B,MAAI,CAAC,WAAW,KAAK,IAAI,QAAQ,CAAE;AACnC,OAAK,IAAI,QAAQ;AACjB,aAAW,KAAK,QAAQ;;AAE1B,QAAO;;AAGT,SAAgB,iBAAiB,UAA8B,SAA2B;AACxF,KAAI,QAAQ,WAAW,EAAG,QAAO,YAAY;CAC7C,MAAM,iBAAiB,YAAY,IAChC,MAAM,KAAK,UAAU,CACrB,KAAK,SAAS,KAAK,MAAM,CAAC,CAC1B,OAAO,QAAQ;CAClB,MAAM,SAAmB,EAAE;CAC3B,MAAM,uBAAO,IAAI,KAAa;AAC9B,MAAK,MAAM,QAAQ,CAAC,GAAG,SAAS,GAAG,cAAc,EAAE;AACjD,MAAI,KAAK,IAAI,KAAK,CAAE;AACpB,OAAK,IAAI,KAAK;AACd,SAAO,KAAK,KAAK;;AAEnB,QAAO,OAAO,KAAK,KAAK,UAAU;;AAGpC,SAAgB,iBACd,KACA,SACA,SACM;AACN,KAAI,CAAC,MAAM,QAAQ,QAAQ,IAAI,QAAQ,WAAW,EAAG;CACrD,MAAM,UAAU,YAAY,IAAI;AAChC,KAAI,SAAS,mBAAmB,CAAC,IAAI,SAAU;CAC/C,MAAM,SAAS,iBAAiB,IAAI,UAAU,QAAQ;AACtD,KAAI,OAAQ,KAAI,WAAW"}

package/dist/src/infra/stable-node-path.d.ts

@@ -0,0 +1,2 @@
+/** Resolve Homebrew Cellar node paths to stable opt/bin symlinks. */
+export declare function resolveStableNodePath(nodePath: string): Promise<string>;

package/dist/src/infra/stable-node-path.js

@@ -0,0 +1,28 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+//#region src/infra/stable-node-path.ts
+/** Resolve Homebrew Cellar node paths to stable opt/bin symlinks. */
+async function resolveStableNodePath(nodePath) {
+	const cellarMatch = nodePath.match(/^(.+?)[\\/]Cellar[\\/]([^\\/]+)[\\/][^\\/]+[\\/]bin[\\/]node$/);
+	if (!cellarMatch) return nodePath;
+	const prefix = cellarMatch[1];
+	const formula = cellarMatch[2];
+	const pathModule = nodePath.includes("\\") ? path.win32 : path.posix;
+	const optPath = pathModule.join(prefix, "opt", formula, "bin", "node");
+	try {
+		await fs.access(optPath);
+		return optPath;
+	} catch {}
+	if (formula === "node") {
+		const binPath = pathModule.join(prefix, "bin", "node");
+		try {
+			await fs.access(binPath);
+			return binPath;
+		} catch {}
+	}
+	return nodePath;
+}
+//#endregion
+export { resolveStableNodePath };
+
+//# sourceMappingURL=stable-node-path.js.map

package/dist/src/infra/stable-node-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stable-node-path.js","names":[],"sources":["../../../src/infra/stable-node-path.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\n\n/** Resolve Homebrew Cellar node paths to stable opt/bin symlinks. */\nexport async function resolveStableNodePath(nodePath: string): Promise<string> {\n  const cellarMatch = nodePath.match(\n    /^(.+?)[\\\\/]Cellar[\\\\/]([^\\\\/]+)[\\\\/][^\\\\/]+[\\\\/]bin[\\\\/]node$/,\n  );\n  if (!cellarMatch) return nodePath;\n\n  const prefix = cellarMatch[1];\n  const formula = cellarMatch[2];\n  const pathModule = nodePath.includes('\\\\') ? path.win32 : path.posix;\n  const optPath = pathModule.join(prefix, 'opt', formula, 'bin', 'node');\n  try {\n    await fs.access(optPath);\n    return optPath;\n  } catch {\n    // fall through\n  }\n\n  if (formula === 'node') {\n    const binPath = pathModule.join(prefix, 'bin', 'node');\n    try {\n      await fs.access(binPath);\n      return binPath;\n    } catch {\n      // fall through\n    }\n  }\n\n  return nodePath;\n}\n"],"mappings":";;;;AAIA,eAAsB,sBAAsB,UAAmC;CAC7E,MAAM,cAAc,SAAS,MAC3B,gEACD;AACD,KAAI,CAAC,YAAa,QAAO;CAEzB,MAAM,SAAS,YAAY;CAC3B,MAAM,UAAU,YAAY;CAC5B,MAAM,aAAa,SAAS,SAAS,KAAK,GAAG,KAAK,QAAQ,KAAK;CAC/D,MAAM,UAAU,WAAW,KAAK,QAAQ,OAAO,SAAS,OAAO,OAAO;AACtE,KAAI;AACF,QAAM,GAAG,OAAO,QAAQ;AACxB,SAAO;SACD;AAIR,KAAI,YAAY,QAAQ;EACtB,MAAM,UAAU,WAAW,KAAK,QAAQ,OAAO,OAAO;AACtD,MAAI;AACF,SAAM,GAAG,OAAO,QAAQ;AACxB,UAAO;UACD;;AAKV,QAAO"}

package/dist/src/infra/update-global.d.ts

@@ -5,41 +5,48 @@ export type ResolvedGlobalInstallCommand = {
     manager: GlobalInstallManager;
     command: string;
 };
-export type GlobalInstallRunResult = {
-    exitCode: number;
-    stdout: string;
-    stderr: string;
-    packageManager: GlobalInstallManager;
-    usedFallback: boolean;
+export type ResolvedGlobalInstallTarget = ResolvedGlobalInstallCommand & {
+    globalRoot: string | null;
+    packageRoot: string | null;
+};
+export type NpmGlobalPrefixLayout = {
+    prefix: string;
+    globalRoot: string;
+    binDir: string;
 };
 export declare function joinGlobalPackagePath(globalRoot: string): string;
 export declare function resolveGlobalInstallCommand(manager: GlobalInstallManager, pkgRoot?: string | null): ResolvedGlobalInstallCommand;
+export declare function resolveNpmGlobalPrefixLayoutFromGlobalRoot(globalRoot?: string | null): NpmGlobalPrefixLayout | null;
+export declare function resolveNpmGlobalPrefixLayoutFromPrefix(prefix: string): NpmGlobalPrefixLayout;
 export declare function createGlobalInstallEnv(env?: NodeJS.ProcessEnv): Promise<NodeJS.ProcessEnv | undefined>;
 export declare function resolveGlobalInstallSpec(params: {
     version: string;
     env?: NodeJS.ProcessEnv;
 }): string;
+export declare function resolveExpectedInstalledVersionFromSpec(spec: string): string | null;
+export declare function collectInstalledGlobalPackageErrors(params: {
+    packageRoot: string;
+    expectedVersion?: string | null;
+}): Promise<string[]>;
 export declare function resolveGlobalRoot(managerOrCommand: GlobalInstallManager | ResolvedGlobalInstallCommand, runCommand: CommandRunner, timeoutMs: number, pkgRoot?: string | null): Promise<string | null>;
-export declare function globalInstallArgs(managerOrCommand: GlobalInstallManager | ResolvedGlobalInstallCommand, spec: string, pkgRoot?: string | null): string[];
-export declare function globalInstallFallbackArgs(managerOrCommand: GlobalInstallManager | ResolvedGlobalInstallCommand, spec: string, pkgRoot?: string | null): string[] | null;
+export declare function resolveGlobalPackageRoot(managerOrCommand: GlobalInstallManager | ResolvedGlobalInstallCommand, runCommand: CommandRunner, timeoutMs: number, pkgRoot?: string | null): Promise<string | null>;
+export declare function resolveGlobalInstallTarget(params: {
+    manager: GlobalInstallManager | ResolvedGlobalInstallCommand;
+    runCommand: CommandRunner;
+    timeoutMs: number;
+    pkgRoot?: string | null;
+}): Promise<ResolvedGlobalInstallTarget>;
+export declare function globalInstallArgs(managerOrCommand: GlobalInstallManager | ResolvedGlobalInstallCommand, spec: string, pkgRoot?: string | null, installPrefix?: string | null): string[];
+export declare function globalInstallFallbackArgs(managerOrCommand: GlobalInstallManager | ResolvedGlobalInstallCommand, spec: string, pkgRoot?: string | null, installPrefix?: string | null): string[] | null;
+export declare function cleanupGlobalRenameDirs(params: {
+    globalRoot: string;
+    packageName: string;
+}): Promise<{
+    removed: string[];
+}>;
 export declare function detectGlobalInstallManagerForRoot(runCommand: CommandRunner, pkgRoot: string, timeoutMs: number): Promise<GlobalInstallManager | null>;
 export declare function detectGlobalInstallManagerByPresence(runCommand: CommandRunner, timeoutMs: number): Promise<GlobalInstallManager | null>;
 export declare function resolveGlobalManager(params: {
     root: string | null;
     timeoutMs?: number;
 }): Promise<GlobalInstallManager>;
-export declare function runGlobalPackageInstall(params: {
-    manager: GlobalInstallManager;
-    spec: string;
-    pkgRoot: string | null;
-    timeoutMs?: number;
-    /** Echo install output to the parent process (CLI interactive). */
-    echoToTerminal?: boolean;
-}): Promise<GlobalInstallRunResult>;
-export declare function formatGlobalInstallFailure(params: {
-    packageManager: GlobalInstallManager;
-    spec: string;
-    exitCode: number;
-    stderr: string;
-    usedFallback: boolean;
-}): string;