@aefree/pi-unity 0.9.0

package/src/unity-processes.ts

@@ -0,0 +1,260 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { commandTargetsProject, type SupportedPlatform } from "./unity-core";
+
+const execFileAsync = promisify(execFile);
+
+export type RunningUnityProcess = {
+  pid: number | null;
+  commandLine: string;
+};
+
+export type UnityProcessTerminationInfo = {
+  forced?: boolean;
+};
+
+const SENSITIVE_FLAG = "(?:-{1,2})?(?:access[-_]?token|auth(?:entication)?[-_]?token|api[-_]?key|client[-_]?secret|credential(?:s)?|password|passwd|secret|token)";
+const SENSITIVE_VALUE = "(?:\"[^\"]*\"|'[^']*'|[^\\s]+)";
+const SENSITIVE_ASSIGNMENT = new RegExp(`(${SENSITIVE_FLAG})(=|:)${SENSITIVE_VALUE}`, "gi");
+const SENSITIVE_SEPARATE_ARGUMENT = new RegExp(`(${SENSITIVE_FLAG})\\s+${SENSITIVE_VALUE}`, "gi");
+
+/** Redact values, not flag names, so diagnostics remain actionable without leaking credentials. */
+export function redactUnityProcessCommandLine(commandLine: string): string {
+  return commandLine
+    .replace(SENSITIVE_ASSIGNMENT, "$1$2[REDACTED]")
+    .replace(SENSITIVE_SEPARATE_ARGUMENT, "$1 [REDACTED]");
+}
+
+export type UnityProcessTerminator = (process: RunningUnityProcess) => Promise<void | UnityProcessTerminationInfo>;
+export type UnityProcessIdentityVerifier = (process: RunningUnityProcess) => Promise<boolean>;
+
+export type TerminateUnityProcessesResult = {
+  terminated: RunningUnityProcess[];
+  forceTerminated: RunningUnityProcess[];
+  skipped: RunningUnityProcess[];
+};
+
+export function parseWindowsUnityProcessList(output: string, projectRoot: string): RunningUnityProcess[] {
+  const trimmed = output.trim();
+  if (!trimmed) {
+    return [];
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return [];
+  }
+
+  const entries = Array.isArray(parsed) ? parsed : [parsed];
+  return entries
+    .map((entry) => {
+      if (!entry || typeof entry !== "object") return null;
+      const record = entry as Record<string, unknown>;
+      const commandLine = typeof record.CommandLine === "string" ? record.CommandLine : "";
+      const pid = typeof record.ProcessId === "number" ? record.ProcessId : null;
+      if (!commandLine || !commandTargetsProject(commandLine, projectRoot, "win32")) {
+        return null;
+      }
+      return { pid, commandLine: redactUnityProcessCommandLine(commandLine) } satisfies RunningUnityProcess;
+    })
+    .filter((entry): entry is RunningUnityProcess => entry !== null);
+}
+
+export function parsePosixUnityProcessList(output: string, projectRoot: string, platform: SupportedPlatform = process.platform): RunningUnityProcess[] {
+  return output
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const match = line.match(/^(\d+)\s+(.*)$/);
+      if (!match) return null;
+      const pid = Number.parseInt(match[1], 10);
+      const commandLine = match[2] ?? "";
+      const looksLikeUnity = /(^|[\/\s"'])Unity(?:\.app\/Contents\/MacOS\/Unity)?(?=$|[\s"'])/.test(commandLine);
+      if (!commandLine || !looksLikeUnity || !commandTargetsProject(commandLine, projectRoot, platform)) {
+        return null;
+      }
+      return {
+        pid: Number.isFinite(pid) ? pid : null,
+        commandLine: redactUnityProcessCommandLine(commandLine),
+      } satisfies RunningUnityProcess;
+    })
+    .filter((entry): entry is RunningUnityProcess => entry !== null);
+}
+
+export function dedupeRunningUnityProcesses(processes: RunningUnityProcess[]): RunningUnityProcess[] {
+  const seenPids = new Set<number>();
+  const seenCommandLines = new Set<string>();
+  const unique: RunningUnityProcess[] = [];
+
+  for (const runningProcess of processes) {
+    if (typeof runningProcess.pid === "number" && Number.isInteger(runningProcess.pid) && runningProcess.pid > 0) {
+      if (seenPids.has(runningProcess.pid)) continue;
+      seenPids.add(runningProcess.pid);
+      unique.push(runningProcess);
+      continue;
+    }
+
+    if (seenCommandLines.has(runningProcess.commandLine)) continue;
+    seenCommandLines.add(runningProcess.commandLine);
+    unique.push(runningProcess);
+  }
+
+  return unique;
+}
+
+function getErrorText(error: unknown): string {
+  if (!error || typeof error !== "object") {
+    return String(error ?? "");
+  }
+
+  const record = error as { stdout?: unknown; stderr?: unknown; message?: unknown };
+  return [record.stdout, record.stderr, record.message]
+    .filter((value): value is string => typeof value === "string")
+    .join("\n");
+}
+
+export function shouldRetryWindowsTaskkillWithForce(error: unknown): boolean {
+  const text = getErrorText(error).toLowerCase();
+  return text.includes("/f") && (
+    text.includes("forcefully") ||
+    text.includes("terminated forcefully") ||
+    text.includes("child process") ||
+    text.includes("child processes")
+  );
+}
+
+export async function defaultUnityProcessTerminator(
+  runningProcess: RunningUnityProcess,
+  platform: SupportedPlatform = process.platform,
+): Promise<UnityProcessTerminationInfo> {
+  if (typeof runningProcess.pid !== "number" || !Number.isInteger(runningProcess.pid) || runningProcess.pid <= 0) {
+    throw new Error(`Cannot close Unity process because no valid PID was reported: ${redactUnityProcessCommandLine(runningProcess.commandLine)}`);
+  }
+
+  if (platform === "win32") {
+    try {
+      await execFileAsync("taskkill.exe", ["/PID", String(runningProcess.pid), "/T"], { timeout: 5000, windowsHide: true });
+      return { forced: false };
+    } catch (error) {
+      if (!shouldRetryWindowsTaskkillWithForce(error)) {
+        throw error;
+      }
+      await execFileAsync("taskkill.exe", ["/PID", String(runningProcess.pid), "/T", "/F"], { timeout: 5000, windowsHide: true });
+      return { forced: true };
+    }
+  }
+
+  process.kill(runningProcess.pid, "SIGTERM");
+  return { forced: false };
+}
+
+export function unityProcessIdentityMatchesCandidates(
+  runningProcess: RunningUnityProcess,
+  candidates: RunningUnityProcess[],
+): boolean {
+  return candidates.some((candidate) => candidate.pid === runningProcess.pid
+    && (runningProcess.commandLine.startsWith("Unity CLI status") || candidate.commandLine === runningProcess.commandLine));
+}
+
+export async function verifyUnityProcessIdentity(
+  runningProcess: RunningUnityProcess,
+  projectRoot: string,
+  platform: SupportedPlatform = process.platform,
+): Promise<boolean> {
+  if (typeof runningProcess.pid !== "number" || !Number.isInteger(runningProcess.pid) || runningProcess.pid <= 0) {
+    return false;
+  }
+
+  try {
+    if (platform === "win32") {
+      const script = [
+        "$ErrorActionPreference='Stop';",
+        `Get-CimInstance Win32_Process -Filter \"ProcessId = ${runningProcess.pid}\"`,
+        "| Select-Object ProcessId, CommandLine",
+        "| ConvertTo-Json -Compress",
+      ].join(" ");
+      const { stdout } = await execFileAsync("powershell.exe", ["-NoProfile", "-Command", script], { timeout: 5000, windowsHide: true });
+      return unityProcessIdentityMatchesCandidates(
+        runningProcess,
+        parseWindowsUnityProcessList(stdout, projectRoot),
+      );
+    }
+
+    const { stdout } = await execFileAsync("ps", ["-p", String(runningProcess.pid), "-o", "pid=,command="], { timeout: 5000 });
+    return unityProcessIdentityMatchesCandidates(
+      runningProcess,
+      parsePosixUnityProcessList(stdout, projectRoot, platform),
+    );
+  } catch {
+    return false;
+  }
+}
+
+export async function terminateRunningUnityProcesses(
+  processes: RunningUnityProcess[],
+  options: {
+    terminator?: UnityProcessTerminator;
+    identityVerifier?: UnityProcessIdentityVerifier;
+    onTerminated?: (runningProcess: RunningUnityProcess, info: UnityProcessTerminationInfo) => void;
+    signal?: AbortSignal;
+  } = {},
+): Promise<TerminateUnityProcessesResult> {
+  const terminator = options.terminator ?? defaultUnityProcessTerminator;
+  const terminated: RunningUnityProcess[] = [];
+  const forceTerminated: RunningUnityProcess[] = [];
+  const skipped: RunningUnityProcess[] = [];
+
+  for (const runningProcess of dedupeRunningUnityProcesses(processes)) {
+    options.signal?.throwIfAborted();
+    if (typeof runningProcess.pid !== "number" || !Number.isInteger(runningProcess.pid) || runningProcess.pid <= 0) {
+      skipped.push(runningProcess);
+      continue;
+    }
+
+    if (options.identityVerifier && !(await options.identityVerifier(runningProcess))) {
+      skipped.push(runningProcess);
+      continue;
+    }
+
+    options.signal?.throwIfAborted();
+    const terminationInfo = await terminator(runningProcess);
+    terminated.push(runningProcess);
+    if (terminationInfo?.forced === true) {
+      forceTerminated.push(runningProcess);
+    }
+    options.onTerminated?.(runningProcess, terminationInfo ?? {});
+  }
+
+  return { terminated, forceTerminated, skipped };
+}
+
+export async function listRunningUnityProcessesForProject(
+  projectRoot: string,
+  platform: SupportedPlatform = process.platform,
+): Promise<{ processes: RunningUnityProcess[]; warning?: string }> {
+  try {
+    if (platform === "win32") {
+      const script = [
+        "$ErrorActionPreference='Stop';",
+        "Get-CimInstance Win32_Process",
+        "| Where-Object { $_.Name -eq 'Unity.exe' }",
+        "| Select-Object ProcessId, CommandLine",
+        "| ConvertTo-Json -Compress",
+      ].join(" ");
+      const { stdout } = await execFileAsync("powershell.exe", ["-NoProfile", "-Command", script], { timeout: 5000, windowsHide: true });
+      return { processes: parseWindowsUnityProcessList(stdout, projectRoot) };
+    }
+
+    const { stdout } = await execFileAsync("ps", ["-ax", "-o", "pid=,command="], { timeout: 5000 });
+    return { processes: parsePosixUnityProcessList(stdout, projectRoot, platform) };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error ?? "Unknown error");
+    return {
+      processes: [],
+      warning: `Could not verify whether Unity is already running for this project: ${message}`,
+    };
+  }
+}

package/src/unity-project-lock.ts

@@ -0,0 +1,381 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { type SupportedPlatform } from "./unity-core";
+import { listRunningUnityProcessesForProject, redactUnityProcessCommandLine, type RunningUnityProcess } from "./unity-processes";
+
+type ProcessListResult = { processes: RunningUnityProcess[]; warning?: string };
+type UnityProcessLister = (projectRoot: string) => Promise<ProcessListResult>;
+type PidAliveCheck = (pid: number) => boolean;
+
+export type UnityProjectBusyState = {
+  projectRoot: string;
+  canonicalProjectRoot: string;
+  nativeLockfilePath: string;
+  nativeLockfileExists: boolean;
+};
+
+export type UnityProjectLaunchMutexMetadata = {
+  projectRoot: string;
+  canonicalProjectRoot: string;
+  ownerPid: number;
+  ownerToken: string;
+  createdAt: string;
+  mode: "batchmode" | "gui";
+  toolName: string;
+};
+
+export type UnityProjectLaunchMutex = {
+  mutexDir: string;
+  metadata: UnityProjectLaunchMutexMetadata;
+  release: () => Promise<void>;
+};
+
+export type UnityProjectBusyOptions = {
+  platform?: SupportedPlatform;
+  processLister?: UnityProcessLister;
+};
+
+export type UnityLaunchSafetyRoute = "unity-cli" | "editor-executable";
+export type UnityLaunchSafetyDecision = { allowed: true; staleLockDelegated?: boolean } | { allowed: false; reason: "process_unknown" | "matching_process" | "native_lockfile" };
+
+/** Pure route matrix used by launch paths: uncertainty and matching editors always block. */
+export function evaluateUnityLaunchSafety(
+  route: UnityLaunchSafetyRoute,
+  state: Pick<UnityProjectBusyState, "nativeLockfileExists">,
+  processes: ProcessListResult,
+): UnityLaunchSafetyDecision {
+  if (processes.warning) return { allowed: false, reason: "process_unknown" };
+  if (processes.processes.length > 0) return { allowed: false, reason: "matching_process" };
+  if (state.nativeLockfileExists && route === "editor-executable") return { allowed: false, reason: "native_lockfile" };
+  return { allowed: true, ...(state.nativeLockfileExists ? { staleLockDelegated: true } : {}) };
+}
+
+export type UnityProjectLaunchMutexOptions = UnityProjectBusyOptions & {
+  mode?: "batchmode" | "gui";
+  toolName?: string;
+  mutexRoot?: string;
+  now?: () => Date;
+  randomToken?: () => string;
+  ownerPid?: number;
+  isPidAlive?: PidAliveCheck;
+};
+
+const METADATA_FILE = "metadata.json";
+
+function defaultMutexRoot(): string {
+  return path.join(os.tmpdir(), "pi-unity-project-locks");
+}
+
+function isNodeErrorWithCode(error: unknown, code: string): boolean {
+  return Boolean(error && typeof error === "object" && "code" in error && (error as { code?: unknown }).code === code);
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getUnityNativeLockfilePath(projectRoot: string): string {
+  return path.join(projectRoot, "Temp", "UnityLockfile");
+}
+
+export async function canonicalizeUnityProjectRoot(
+  projectRoot: string,
+  platform: SupportedPlatform = process.platform,
+): Promise<string> {
+  const absoluteProjectRoot = path.resolve(projectRoot);
+  let realProjectRoot: string;
+  try {
+    realProjectRoot = await fs.realpath(absoluteProjectRoot);
+  } catch {
+    realProjectRoot = absoluteProjectRoot;
+  }
+
+  const normalized = path.normalize(realProjectRoot);
+  return platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+export function getUnityProjectMutexDir(canonicalProjectRoot: string, mutexRoot: string = defaultMutexRoot()): string {
+  const hash = crypto.createHash("sha256").update(canonicalProjectRoot).digest("hex").slice(0, 32);
+  return path.join(mutexRoot, hash);
+}
+
+function defaultIsPidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (isNodeErrorWithCode(error, "ESRCH")) {
+      return false;
+    }
+    return true;
+  }
+}
+
+function buildProcessSummary(processes: RunningUnityProcess[]): string {
+  return processes
+    .map((process) => `${process.pid ?? "?"}: ${redactUnityProcessCommandLine(process.commandLine)}`)
+    .join("\n");
+}
+
+async function listProcessesSafely(processLister: UnityProcessLister, projectRoot: string): Promise<ProcessListResult> {
+  try {
+    return await processLister(projectRoot);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error ?? "Unknown error");
+    return { processes: [], warning: `Could not verify whether Unity is already running for this project: ${message}` };
+  }
+}
+
+export async function inspectUnityProjectBusyState(
+  projectRoot: string,
+  options: UnityProjectBusyOptions = {},
+): Promise<UnityProjectBusyState> {
+  const canonicalProjectRoot = await canonicalizeUnityProjectRoot(projectRoot, options.platform);
+  const nativeLockfilePath = getUnityNativeLockfilePath(projectRoot);
+  const nativeLockfileExists = await pathExists(nativeLockfilePath);
+  return {
+    projectRoot,
+    canonicalProjectRoot,
+    nativeLockfilePath,
+    nativeLockfileExists,
+  };
+}
+
+export async function assertUnityProjectNotBusy(
+  projectRoot: string,
+  options: UnityProjectBusyOptions = {},
+): Promise<UnityProjectBusyState> {
+  const state = await inspectUnityProjectBusyState(projectRoot, options);
+  if (!state.nativeLockfileExists) {
+    return state;
+  }
+
+  const processLister = options.processLister ?? listRunningUnityProcessesForProject;
+  const running = await listProcessesSafely(processLister, projectRoot);
+  if (running.warning) {
+    throw new Error(
+      [
+        `Refusing to launch Unity for ${projectRoot} because Unity's native project lockfile exists and running-process verification failed.`,
+        `Unity lockfile: ${state.nativeLockfilePath}`,
+        running.warning,
+        "Inspect the project manually before removing the lockfile or retrying.",
+      ].join("\n"),
+    );
+  }
+
+  if (running.processes.length > 0) {
+    throw new Error(
+      [
+        `Refusing to launch Unity for ${projectRoot} because Unity's native project lockfile exists and a Unity process targets this project.`,
+        `Unity lockfile: ${state.nativeLockfilePath}`,
+        buildProcessSummary(running.processes),
+      ].join("\n"),
+    );
+  }
+
+  throw new Error(
+    [
+      `Refusing to launch Unity for ${projectRoot} because Unity's native project lockfile exists.`,
+      `Unity lockfile: ${state.nativeLockfilePath}`,
+      "No running Unity process targeting this project was detected; this may be a stale Unity lockfile.",
+      "Remove the lockfile manually only after confirming no Unity process is using this project.",
+    ].join("\n"),
+  );
+}
+
+function metadataPath(mutexDir: string): string {
+  return path.join(mutexDir, METADATA_FILE);
+}
+
+function parseMutexMetadata(raw: string): UnityProjectLaunchMutexMetadata | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  if (!parsed || typeof parsed !== "object") {
+    return null;
+  }
+
+  const record = parsed as Record<string, unknown>;
+  if (
+    typeof record.projectRoot !== "string" ||
+    typeof record.canonicalProjectRoot !== "string" ||
+    typeof record.ownerPid !== "number" ||
+    typeof record.ownerToken !== "string" ||
+    typeof record.createdAt !== "string" ||
+    (record.mode !== "batchmode" && record.mode !== "gui") ||
+    typeof record.toolName !== "string"
+  ) {
+    return null;
+  }
+
+  return record as UnityProjectLaunchMutexMetadata;
+}
+
+async function readMutexMetadata(mutexDir: string): Promise<UnityProjectLaunchMutexMetadata | null> {
+  try {
+    const raw = await fs.readFile(metadataPath(mutexDir), "utf8");
+    return parseMutexMetadata(raw);
+  } catch {
+    return null;
+  }
+}
+
+function buildMutexConflictMessage(projectRoot: string, metadata: UnityProjectLaunchMutexMetadata, mutexDir: string): string {
+  return [
+    `Refusing to launch Unity for ${projectRoot} because another Pi Unity launch already holds the project mutex.`,
+    `Mutex: ${mutexDir}`,
+    `Owner pid: ${metadata.ownerPid}`,
+    `Owner tool: ${metadata.toolName}`,
+    `Owner mode: ${metadata.mode}`,
+    `Created at: ${metadata.createdAt}`,
+  ].join("\n");
+}
+
+async function clearStaleMutexOrThrow(
+  projectRoot: string,
+  mutexDir: string,
+  metadata: UnityProjectLaunchMutexMetadata,
+  options: UnityProjectLaunchMutexOptions,
+): Promise<void> {
+  const isPidAlive = options.isPidAlive ?? defaultIsPidAlive;
+  if (isPidAlive(metadata.ownerPid)) {
+    throw new Error(buildMutexConflictMessage(projectRoot, metadata, mutexDir));
+  }
+
+  const busyState = await inspectUnityProjectBusyState(projectRoot, options);
+  if (busyState.nativeLockfileExists) {
+    throw new Error(
+      [
+        `Refusing to clear a stale Pi Unity launch mutex for ${projectRoot} because Unity's native project lockfile exists.`,
+        `Mutex: ${mutexDir}`,
+        `Unity lockfile: ${busyState.nativeLockfilePath}`,
+        "Inspect the project manually before retrying.",
+      ].join("\n"),
+    );
+  }
+
+  const processLister = options.processLister ?? listRunningUnityProcessesForProject;
+  const running = await listProcessesSafely(processLister, projectRoot);
+  if (running.warning) {
+    throw new Error(
+      [
+        `Refusing to clear a stale Pi Unity launch mutex for ${projectRoot} because running-process verification failed.`,
+        `Mutex: ${mutexDir}`,
+        running.warning,
+      ].join("\n"),
+    );
+  }
+
+  if (running.processes.length > 0) {
+    throw new Error(
+      [
+        `Refusing to clear a stale Pi Unity launch mutex for ${projectRoot} because a Unity process still targets this project.`,
+        `Mutex: ${mutexDir}`,
+        buildProcessSummary(running.processes),
+      ].join("\n"),
+    );
+  }
+
+  await fs.rm(mutexDir, { recursive: true, force: true });
+}
+
+export async function releaseUnityProjectLaunchMutex(mutexDir: string, ownerToken: string): Promise<void> {
+  const metadata = await readMutexMetadata(mutexDir);
+  if (!metadata || metadata.ownerToken !== ownerToken) {
+    return;
+  }
+
+  await fs.rm(mutexDir, { recursive: true, force: true });
+}
+
+export async function acquireUnityProjectLaunchMutex(
+  projectRoot: string,
+  options: UnityProjectLaunchMutexOptions = {},
+): Promise<UnityProjectLaunchMutex> {
+  const canonicalProjectRoot = await canonicalizeUnityProjectRoot(projectRoot, options.platform);
+  const mutexRoot = options.mutexRoot ?? defaultMutexRoot();
+  const mutexDir = getUnityProjectMutexDir(canonicalProjectRoot, mutexRoot);
+  await fs.mkdir(mutexRoot, { recursive: true });
+
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      await fs.mkdir(mutexDir);
+      const metadata: UnityProjectLaunchMutexMetadata = {
+        projectRoot,
+        canonicalProjectRoot,
+        ownerPid: options.ownerPid ?? process.pid,
+        ownerToken: options.randomToken?.() ?? crypto.randomUUID(),
+        createdAt: (options.now?.() ?? new Date()).toISOString(),
+        mode: options.mode ?? "batchmode",
+        toolName: options.toolName ?? "unity_launch_batchmode",
+      };
+
+      try {
+        await fs.writeFile(metadataPath(mutexDir), `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+      } catch (error) {
+        await fs.rm(mutexDir, { recursive: true, force: true });
+        throw error;
+      }
+
+      return {
+        mutexDir,
+        metadata,
+        release: () => releaseUnityProjectLaunchMutex(mutexDir, metadata.ownerToken),
+      };
+    } catch (error) {
+      if (!isNodeErrorWithCode(error, "EEXIST")) {
+        throw error;
+      }
+
+      const metadata = await readMutexMetadata(mutexDir);
+      if (!metadata) {
+        throw new Error(
+          [
+            `Refusing to launch Unity for ${projectRoot} because a Pi Unity launch mutex exists but its metadata could not be read.`,
+            `Mutex: ${mutexDir}`,
+            "Inspect the mutex manually before removing it or retrying.",
+          ].join("\n"),
+        );
+      }
+
+      await clearStaleMutexOrThrow(projectRoot, mutexDir, metadata, options);
+    }
+  }
+
+  throw new Error(`Refusing to launch Unity for ${projectRoot} because the Pi Unity launch mutex could not be acquired.`);
+}
+
+export async function withUnityProjectLaunchMutex<T>(
+  projectRoot: string,
+  options: UnityProjectLaunchMutexOptions,
+  callback: () => Promise<T>,
+): Promise<T> {
+  const mutex = await acquireUnityProjectLaunchMutex(projectRoot, options);
+  try {
+    return await callback();
+  } finally {
+    await mutex.release();
+  }
+}
+
+export const __unityProjectLockInternals = {
+  canonicalizeUnityProjectRoot,
+  getUnityNativeLockfilePath,
+  getUnityProjectMutexDir,
+  defaultIsPidAlive,
+};