Repair cached Python directory junctions on Windows (#1122)

With `cache-python: true`, a Windows runner can report a cache hit while
extracting the cache incorrectly. When `@actions/cache`'s tar extracts
uv's minor-version junction before the patch directory it points to, it
creates a file symlink. Resolving that link later raises `[WinError 5]
Access is denied`.

This PR fixes things up after restoring the Python cache, recreating the
junction if resolving the link fails with access denied and its recorded
target is a matching, accessible CPython installation in the same
directory.

This is a temporary workaround until
https://github.com/actions/toolkit/issues/2562 gets resolved and
`@actions/cache` itself becomes resilient to these situations.

I tested this by restoring the same archive on two fresh `windows-2022`
runners. The original run passed because resolving the minor-version
link raised the expected WinError 5. With the patch, `uv sync --offline
--managed-python --no-python-downloads` created a virtual environment
whose `home` in `pyvenv.cfg` resolved to the cached CPython 3.10.22
installation. [Original
run](https://github.com/astral-sh/ruff/actions/runs/41469344610/job/125358623949#step:9:1)
· [Patched
run](https://github.com/astral-sh/ruff/actions/runs/41469344610/job/125358623835#step:10:1).

src/cache/repair-python-junctions.ts

@@ -0,0 +1,60 @@
+import { readdir, readlink, realpath, symlink, unlink } from "node:fs/promises";
+import nodePath from "node:path";
+
+export async function repairPythonJunctions(pythonDir: string): Promise<void> {
+  const entries = await readdir(pythonDir, { withFileTypes: true });
+  const directories = new Set(
+    entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name.toLowerCase()),
+  );
+
+  for (const entry of entries) {
+    const name = entry.name.toLowerCase();
+    if (!entry.isSymbolicLink() || !/^cpython-\d+\.\d+[+-].+$/.test(name)) {
+      continue;
+    }
+    const link = nodePath.join(pythonDir, entry.name);
+    let target: string;
+    try {
+      target = nodePath.resolve(pythonDir, await readlink(link));
+    } catch (err) {
+      // Fail only if the link still has the access error that requires repair.
+      if (await resolvesWithAccessDenied(link)) {
+        throw err;
+      }
+      continue;
+    }
+
+    // uv omits only the patch and prerelease from its minor-version links.
+    const sibling = nodePath.relative(pythonDir, target).toLowerCase();
+    const version = /^(cpython-\d+\.\d+)\.\d+(?:(?:a|b|rc)\d+)?([+-].+)$/.exec(
+      sibling,
+    );
+    if (
+      !version ||
+      version[1] + version[2] !== name ||
+      !directories.has(sibling)
+    ) {
+      continue;
+    }
+    // Git for Windows tar can restore a junction as a file symlink when it
+    // extracts the link before its target. Opening it as a directory fails.
+    if (!(await resolvesWithAccessDenied(link))) {
+      continue;
+    }
+    // An inaccessible installation can also cause EPERM through a valid link.
+    await realpath(target);
+    await unlink(link);
+    await symlink(target, link, "junction");
+  }
+}
+
+async function resolvesWithAccessDenied(link: string): Promise<boolean> {
+  try {
+    await realpath(link);
+    return false;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}

src/cache/restore-cache.ts

@@ -4,6 +4,7 @@ import { hashFiles } from "../hash/hash-files";
 import type { SetupInputs } from "../utils/inputs";
 import * as log from "../utils/logging";
 import { getArch, getOSNameVersion, getPlatform } from "../utils/platforms";
+import { repairPythonJunctions } from "./repair-python-junctions";
 
 export const STATE_CACHE_KEY = "cache-key";
 export const STATE_CACHE_MATCHED_KEY = "cache-matched-key";
@@ -44,6 +45,9 @@ export async function restoreCache(
       inputs.pythonDir,
       STATE_PYTHON_CACHE_MATCHED_KEY,
       "python-cache-hit",
+      // TODO: Remove this repair once @actions/cache preserves Windows junctions.
+      // https://github.com/actions/toolkit/issues/2562
+      process.platform === "win32" ? repairPythonJunctions : undefined,
     );
   } else {
     core.setOutput("python-cache-hit", false);
@@ -55,21 +59,33 @@ async function restoreCacheFromKey(
   cachePath: string,
   stateKey: string,
   outputKey: string,
+  afterRestore?: (cachePath: string) => Promise<void>,
 ): Promise<void> {
   log.info(
     `Trying to restore cache from GitHub Actions cache with key: ${cacheKey}`,
   );
-  let matchedKey: string | undefined;
   try {
-    matchedKey = await cache.restoreCache([cachePath], cacheKey);
+    const matchedKey = await cache.restoreCache([cachePath], cacheKey);
+    if (!matchedKey) {
+      log.info(`No GitHub Actions cache found for key: ${cacheKey}`);
+      core.setOutput(outputKey, false);
+      return;
+    }
+
+    // Record the match before the post-restore hook so the post step can skip
+    // archiving the directory again even if the hook fails. A PR that restored
+    // from its base branch could otherwise save the broken copy in its own cache.
+    core.saveState(stateKey, matchedKey);
+    await afterRestore?.(cachePath);
+    log.info(
+      `cache restored from GitHub Actions cache with key: ${matchedKey}`,
+    );
+    core.setOutput(outputKey, true);
   } catch (err) {
     const message = (err as Error).message;
     log.warning(message);
     core.setOutput(outputKey, false);
-    return;
   }
-
-  handleMatchResult(matchedKey, cacheKey, stateKey, outputKey);
 }
 
 async function computeKeys(
@@ -107,20 +123,3 @@ async function computeKeys(
   const python = inputs.cachePython ? "-py" : "";
   return `setup-uv-${CACHE_VERSION}-${getArch()}-${platform}-${osNameVersion}-${version}${pythonArchKey}${pruned}${python}${cacheDependencyPathHash}${suffix}`;
 }
-
-function handleMatchResult(
-  matchedKey: string | undefined,
-  primaryKey: string,
-  stateKey: string,
-  outputKey: string,
-): void {
-  if (!matchedKey) {
-    log.info(`No GitHub Actions cache found for key: ${primaryKey}`);
-    core.setOutput(outputKey, false);
-    return;
-  }
-
-  core.saveState(stateKey, matchedKey);
-  log.info(`cache restored from GitHub Actions cache with key: ${matchedKey}`);
-  core.setOutput(outputKey, true);
-}