Switch to ESM for source and test, use CommonJS for dist

.github/workflows/test.yml

@@ -38,7 +38,7 @@ jobs:
           npm run all
       - name: Check all jobs are in all-tests-passed.needs
         run: |
-          tsc check-all-tests-passed-needs.ts
+          tsc --module nodenext --moduleResolution nodenext --target es2022 check-all-tests-passed-needs.ts
           node check-all-tests-passed-needs.js
         working-directory: .github/scripts
       - name: Make sure no changes from linters are detected

.github/workflows/update-known-checksums.yml

@@ -20,11 +20,12 @@ jobs:
           persist-credentials: true
       - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
-          node-version: "20"
+          node-version-file: .nvmrc
+          cache: npm
       - name: Update known checksums
         id: update-known-checksums
         run:
-          node dist/update-known-checksums/index.js
+          node dist/update-known-checksums/index.cjs
           src/download/checksum/known-checksums.ts
       - name: Check for changes
         id: changes-exist

AGENTS.md

@@ -10,4 +10,9 @@ This repository is a TypeScript-based GitHub Action for installing `uv` in GitHu
 - User-facing changes are usually multi-file changes. If you add or change inputs, outputs, or behavior, update `action.yml`, the implementation in `src/`, tests in `__tests__/`, relevant docs/README, and then re-package.
 - The easiest areas to regress are version resolution and caching. When touching them, add or update tests for precedence, cache invalidation, and cross-platform path behavior.
 - Workflow edits have extra CI-only checks (`actionlint` and `zizmor`); `npm run all` does not cover them.
+- Source is authored with bundler-friendly TypeScript, but published action artifacts in `dist/` are bundled as CommonJS for maximum GitHub Actions runtime compatibility with `@actions/*` dependencies.
+- Keep these concerns separate when changing module formats:
+  - `src/` and tests may use modern ESM-friendly TypeScript patterns.
+  - `dist/` should prioritize runtime reliability over format purity.
+  - Do not switch published bundles to ESM without validating the actual committed artifacts under the target Node runtime.
 - Before finishing, make sure validation does not leave generated or formatting-only diffs behind.

__tests__/download/download-version.test.ts

@@ -1,9 +1,10 @@
 import { beforeEach, describe, expect, it, jest } from "@jest/globals";
+import * as semver from "semver";
 
 const mockInfo = jest.fn();
 const mockWarning = jest.fn();
 
-jest.mock("@actions/core", () => ({
+jest.unstable_mockModule("@actions/core", () => ({
   debug: jest.fn(),
   info: mockInfo,
   warning: mockWarning,
@@ -18,20 +19,17 @@ const mockExtractZip = jest.fn<any>();
 // biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
 const mockCacheDir = jest.fn<any>();
 
-jest.mock("@actions/tool-cache", () => {
-  const actual = jest.requireActual("@actions/tool-cache") as Record<
-    string,
-    unknown
-  >;
-
-  return {
-    ...actual,
-    cacheDir: mockCacheDir,
-    downloadTool: mockDownloadTool,
-    extractTar: mockExtractTar,
-    extractZip: mockExtractZip,
-  };
-});
+jest.unstable_mockModule("@actions/tool-cache", () => ({
+  cacheDir: mockCacheDir,
+  downloadTool: mockDownloadTool,
+  evaluateVersions: (versions: string[], range: string) =>
+    semver.maxSatisfying(versions, range) ?? "",
+  extractTar: mockExtractTar,
+  extractZip: mockExtractZip,
+  find: () => "",
+  findAllVersions: () => [],
+  isExplicitVersion: (version: string) => semver.valid(version) !== null,
+}));
 
 // biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
 const mockGetLatestVersionFromNdjson = jest.fn<any>();
@@ -40,7 +38,7 @@ const mockGetAllVersionsFromNdjson = jest.fn<any>();
 // biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
 const mockGetArtifactFromNdjson = jest.fn<any>();
 
-jest.mock("../../src/download/versions-client", () => ({
+jest.unstable_mockModule("../../src/download/versions-client", () => ({
   getAllVersions: mockGetAllVersionsFromNdjson,
   getArtifact: mockGetArtifactFromNdjson,
   getLatestVersion: mockGetLatestVersionFromNdjson,
@@ -53,7 +51,7 @@ const mockGetLatestVersionInManifest = jest.fn<any>();
 // biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
 const mockGetManifestArtifact = jest.fn<any>();
 
-jest.mock("../../src/download/version-manifest", () => ({
+jest.unstable_mockModule("../../src/download/version-manifest", () => ({
   getAllVersions: mockGetAllManifestVersions,
   getLatestKnownVersion: mockGetLatestVersionInManifest,
   getManifestArtifact: mockGetManifestArtifact,
@@ -62,15 +60,15 @@ jest.mock("../../src/download/version-manifest", () => ({
 // biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
 const mockValidateChecksum = jest.fn<any>();
 
-jest.mock("../../src/download/checksum/checksum", () => ({
+jest.unstable_mockModule("../../src/download/checksum/checksum", () => ({
   validateChecksum: mockValidateChecksum,
 }));
 
-import {
+const {
   downloadVersionFromManifest,
   downloadVersionFromNdjson,
   resolveVersion,
-} from "../../src/download/download-version";
+} = await import("../../src/download/download-version");
 
 describe("download-version", () => {
   beforeEach(() => {

__tests__/download/version-manifest.test.ts

@@ -2,24 +2,24 @@ import { beforeEach, describe, expect, it, jest } from "@jest/globals";
 
 const mockWarning = jest.fn();
 
-jest.mock("@actions/core", () => ({
+jest.unstable_mockModule("@actions/core", () => ({
   debug: jest.fn(),
   info: jest.fn(),
   warning: mockWarning,
 }));
 
 // biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
 const mockFetch = jest.fn<any>();
-jest.mock("../../src/utils/fetch", () => ({
+jest.unstable_mockModule("../../src/utils/fetch", () => ({
   fetch: mockFetch,
 }));
 
-import {
+const {
   clearManifestCache,
   getAllVersions,
   getLatestKnownVersion,
   getManifestArtifact,
-} from "../../src/download/version-manifest";
+} = await import("../../src/download/version-manifest");
 
 const legacyManifestResponse = JSON.stringify([
   {

__tests__/download/versions-client.test.ts

@@ -2,18 +2,19 @@ import { beforeEach, describe, expect, it, jest } from "@jest/globals";
 
 // biome-ignore lint/suspicious/noExplicitAny: Mock requires flexible typing in tests.
 const mockFetch = jest.fn<any>();
-jest.mock("../../src/utils/fetch", () => ({
+
+jest.unstable_mockModule("../../src/utils/fetch", () => ({
   fetch: mockFetch,
 }));
 
-import {
+const {
   clearCache,
   fetchVersionData,
   getAllVersions,
   getArtifact,
   getLatestVersion,
   parseVersionData,
-} from "../../src/download/versions-client";
+} = await import("../../src/download/versions-client");
 
 const sampleNdjsonResponse = `{"version":"0.9.26","artifacts":[{"platform":"aarch64-apple-darwin","variant":"default","url":"https://github.com/astral-sh/uv/releases/download/0.9.26/uv-aarch64-apple-darwin.tar.gz","archive_format":"tar.gz","sha256":"fcf0a9ea6599c6ae28a4c854ac6da76f2c889354d7c36ce136ef071f7ab9721f"},{"platform":"x86_64-pc-windows-msvc","variant":"default","url":"https://github.com/astral-sh/uv/releases/download/0.9.26/uv-x86_64-pc-windows-msvc.zip","archive_format":"zip","sha256":"eb02fd95d8e0eed462b4a67ecdd320d865b38c560bffcda9a0b87ec944bdf036"}]}
 {"version":"0.9.25","artifacts":[{"platform":"aarch64-apple-darwin","variant":"default","url":"https://github.com/astral-sh/uv/releases/download/0.9.25/uv-aarch64-apple-darwin.tar.gz","archive_format":"tar.gz","sha256":"606b3c6949d971709f2526fa0d9f0fd23ccf60e09f117999b406b424af18a6a6"}]}`;

__tests__/utils/inputs.test.ts

@@ -1,14 +1,3 @@
-jest.mock("@actions/core", () => {
-  return {
-    debug: jest.fn(),
-    getBooleanInput: jest.fn(
-      (name: string) => (mockInputs[name] ?? "") === "true",
-    ),
-    getInput: jest.fn((name: string) => mockInputs[name] ?? ""),
-    warning: jest.fn(),
-  };
-});
-
 import {
   afterEach,
   beforeEach,
@@ -22,6 +11,26 @@ import {
 let mockInputs: Record<string, string> = {};
 const ORIGINAL_HOME = process.env.HOME;
 
+const mockDebug = jest.fn();
+const mockGetBooleanInput = jest.fn(
+  (name: string) => (mockInputs[name] ?? "") === "true",
+);
+const mockGetInput = jest.fn((name: string) => mockInputs[name] ?? "");
+const mockInfo = jest.fn();
+const mockWarning = jest.fn();
+
+jest.unstable_mockModule("@actions/core", () => ({
+  debug: mockDebug,
+  getBooleanInput: mockGetBooleanInput,
+  getInput: mockGetInput,
+  info: mockInfo,
+  warning: mockWarning,
+}));
+
+async function importInputsModule() {
+  return await import("../../src/utils/inputs");
+}
+
 describe("cacheDependencyGlob", () => {
   beforeEach(() => {
     jest.resetModules();
@@ -36,29 +45,29 @@ describe("cacheDependencyGlob", () => {
 
   it("returns empty string when input not provided", async () => {
     mockInputs["working-directory"] = "/workspace";
-    const { cacheDependencyGlob } = await import("../../src/utils/inputs");
+    const { cacheDependencyGlob } = await importInputsModule();
     expect(cacheDependencyGlob).toBe("");
   });
 
   it("resolves a single relative path", async () => {
     mockInputs["working-directory"] = "/workspace";
     mockInputs["cache-dependency-glob"] = "requirements.txt";
-    const { cacheDependencyGlob } = await import("../../src/utils/inputs");
+    const { cacheDependencyGlob } = await importInputsModule();
     expect(cacheDependencyGlob).toBe("/workspace/requirements.txt");
   });
 
   it("strips leading ./ from relative path", async () => {
     mockInputs["working-directory"] = "/workspace";
     mockInputs["cache-dependency-glob"] = "./uv.lock";
-    const { cacheDependencyGlob } = await import("../../src/utils/inputs");
+    const { cacheDependencyGlob } = await importInputsModule();
     expect(cacheDependencyGlob).toBe("/workspace/uv.lock");
   });
 
   it("handles multiple lines, trimming whitespace, tilde expansion and absolute paths", async () => {
     mockInputs["working-directory"] = "/workspace";
     mockInputs["cache-dependency-glob"] =
       "  ~/.cache/file1\n ./rel/file2  \nfile3.txt";
-    const { cacheDependencyGlob } = await import("../../src/utils/inputs");
+    const { cacheDependencyGlob } = await importInputsModule();
     expect(cacheDependencyGlob).toBe(
       [
         "/home/testuser/.cache/file1", // expanded tilde, absolute path unchanged
@@ -71,7 +80,7 @@ describe("cacheDependencyGlob", () => {
   it("keeps absolute path unchanged in multiline input", async () => {
     mockInputs["working-directory"] = "/workspace";
     mockInputs["cache-dependency-glob"] = "/abs/path.lock\nrelative.lock";
-    const { cacheDependencyGlob } = await import("../../src/utils/inputs");
+    const { cacheDependencyGlob } = await importInputsModule();
     expect(cacheDependencyGlob).toBe(
       ["/abs/path.lock", "/workspace/relative.lock"].join("\n"),
     );
@@ -80,7 +89,7 @@ describe("cacheDependencyGlob", () => {
   it("handles exclusions in relative paths correct", async () => {
     mockInputs["working-directory"] = "/workspace";
     mockInputs["cache-dependency-glob"] = "!/abs/path.lock\n!relative.lock";
-    const { cacheDependencyGlob } = await import("../../src/utils/inputs");
+    const { cacheDependencyGlob } = await importInputsModule();
     expect(cacheDependencyGlob).toBe(
       ["!/abs/path.lock", "!/workspace/relative.lock"].join("\n"),
     );
@@ -104,7 +113,7 @@ describe("tool directories", () => {
     mockInputs["tool-bin-dir"] = "~/tool-bin-dir";
     mockInputs["tool-dir"] = "~/tool-dir";
 
-    const { toolBinDir, toolDir } = await import("../../src/utils/inputs");
+    const { toolBinDir, toolDir } = await importInputsModule();
 
     expect(toolBinDir).toBe("/home/testuser/tool-bin-dir");
     expect(toolDir).toBe("/home/testuser/tool-dir");
@@ -127,9 +136,7 @@ describe("cacheLocalPath", () => {
     mockInputs["working-directory"] = "/workspace";
     mockInputs["cache-local-path"] = "~/uv-cache/cache-local-path";
 
-    const { CacheLocalSource, cacheLocalPath } = await import(
-      "../../src/utils/inputs"
-    );
+    const { CacheLocalSource, cacheLocalPath } = await importInputsModule();
 
     expect(cacheLocalPath).toEqual({
       path: "/home/testuser/uv-cache/cache-local-path",
@@ -152,58 +159,51 @@ describe("venvPath", () => {
 
   it("defaults to .venv in the working directory", async () => {
     mockInputs["working-directory"] = "/workspace";
-    const { venvPath } = await import("../../src/utils/inputs");
+    const { venvPath } = await importInputsModule();
     expect(venvPath).toBe("/workspace/.venv");
   });
 
   it("resolves a relative venv-path", async () => {
     mockInputs["working-directory"] = "/workspace";
     mockInputs["activate-environment"] = "true";
     mockInputs["venv-path"] = "custom-venv";
-    const { venvPath } = await import("../../src/utils/inputs");
+    const { venvPath } = await importInputsModule();
     expect(venvPath).toBe("/workspace/custom-venv");
   });
 
   it("normalizes venv-path with trailing slash", async () => {
     mockInputs["working-directory"] = "/workspace";
     mockInputs["activate-environment"] = "true";
     mockInputs["venv-path"] = "custom-venv/";
-    const { venvPath } = await import("../../src/utils/inputs");
+    const { venvPath } = await importInputsModule();
     expect(venvPath).toBe("/workspace/custom-venv");
   });
 
   it("keeps an absolute venv-path unchanged", async () => {
     mockInputs["working-directory"] = "/workspace";
     mockInputs["activate-environment"] = "true";
     mockInputs["venv-path"] = "/tmp/custom-venv";
-    const { venvPath } = await import("../../src/utils/inputs");
+    const { venvPath } = await importInputsModule();
     expect(venvPath).toBe("/tmp/custom-venv");
   });
 
   it("expands tilde in venv-path", async () => {
     mockInputs["working-directory"] = "/workspace";
     mockInputs["activate-environment"] = "true";
     mockInputs["venv-path"] = "~/.venv";
-    const { venvPath } = await import("../../src/utils/inputs");
+    const { venvPath } = await importInputsModule();
     expect(venvPath).toBe("/home/testuser/.venv");
   });
 
   it("warns when venv-path is set but activate-environment is false", async () => {
     mockInputs["working-directory"] = "/workspace";
     mockInputs["venv-path"] = "custom-venv";
 
-    const { activateEnvironment, venvPath } = await import(
-      "../../src/utils/inputs"
-    );
+    const { activateEnvironment, venvPath } = await importInputsModule();
 
     expect(activateEnvironment).toBe(false);
     expect(venvPath).toBe("/workspace/custom-venv");
-
-    const mockedCore = jest.requireMock("@actions/core") as {
-      warning: jest.Mock;
-    };
-
-    expect(mockedCore.warning).toHaveBeenCalledWith(
+    expect(mockWarning).toHaveBeenCalledWith(
       "venv-path is only used when activate-environment is true",
     );
   });