Add support for @actions/cache (#217)

This pull request introduces support for the `@actions/cache` package
for local testing, enhances the `.env.example` file with more
comprehensive documentation and variables, and updates documentation to
reflect these changes. It also adds new test stubs and minor version
bumps for toolkit dependencies.

**Local caching and environment variable enhancements:**

- Added support for the `@actions/cache` package, enabling local caching
of dependencies and files between runs by requiring the
`LOCAL_ACTION_CACHE_PATH` environment variable. Also clarified
requirements for `@actions/artifact` and `@actions/cache` in the
changelog.
- Major overhaul of `.env.example` to include detailed documentation,
default values, and grouping of variables for `@github/local-action`,
GitHub Actions inputs, and runner/environment variables. Added new
variables such as `LOCAL_ACTION_CACHE_PATH`, `LOCAL_ACTION_WORKSPACE`,
and provided more explicit defaults for local testing.

**Documentation and toolkit stub management:**

- Added instructions in `CONTRIBUTING.md` for updating toolkit stubs,
including how to track reviewed versions and compare toolkit package
changes, to ensure consistency and easier maintenance.
- Updated the supported version of `@actions/github` in the `README.md`
from `6.0.0` to `6.0.1`.

**Testing and stub improvements:**

- Added a stub for `@actions/io` in `__fixtures__/@actions/io.ts` for
use in tests, implementing mock versions of `which` and `mkdirP`.
- Added a stub for `isDebug` to the `@actions/core` test fixture.

Author: ncalteen

.env.example

@@ -1,5 +1,18 @@
 # Changelog
 
+## v6
+
+Adds support for the `@actions/cache` package, allowing for local caching of
+dependencies and other files between runs of a GitHub Action. This is achieved
+by setting the `LOCAL_ACTION_CACHE_PATH` environment variable to a directory
+where cache files will be stored.
+
+For both `@actions/artifact` and `@actions/cache`, the `LOCAL_ACTION_WORKSPACE`
+environment variable must be set. Otherwise, calling functions will throw an
+error. Similarly, `@actions/artifact` requires the `LOCAL_ACTION_ARTIFACT_PATH`
+environment variable to be set, and `@actions/cache` requires the
+`LOCAL_ACTION_CACHE_PATH` environment variable to be set.
+
 ## v5
 
 Removes support for custom `paths` in the target action's `tsconfig.json`. This

CHANGELOG.md

@@ -104,3 +104,37 @@ npm run test
 > [!NOTE]
 >
 > This requires that you have already run `npm install`
+
+### Toolkit Stub Updates
+
+When updating any of the supported stubs for the GitHub Actions Toolkit, please
+make sure to also update the following. This helps ensure that we are using the
+latest supported versions of the toolkit packages, and makes comparing changes
+across commits easier.
+
+1. The supported version in the [`README.md`](./README.md)
+
+   ```markdown
+   | Package                                                                | Version  |
+   | ---------------------------------------------------------------------- | -------- |
+   | [`@actions/artifact`](https://www.npmjs.com/package/@actions/artifact) | `2.3.2`  |
+   | [`@actions/core`](https://www.npmjs.com/package/@actions/core)         | `1.11.1` |
+   | [`@actions/github`](https://www.npmjs.com/package/@actions/github)     | `6.0.1`  |
+   ```
+
+1. The latest reviewed commit URL in the corresponding `src/stubs/*.ts` file
+
+   ```typescript
+   /**
+    * Last Reviewed Commit: https://github.com/actions/toolkit/blob/f58042f9cc16bcaa87afaa86c2974a8c771ce1ea/packages/artifact/src/artifact.ts
+    * Last Reviewed Date: 2025-09-10
+    */
+   ```
+
+When comparing commits to see what has been updated in the toolkit packages, be
+sure to compare against the last reviewed commit in the corresponding stub file.
+This can be done more easily using the following URL format:
+
+```plain
+https://github.com/actions/toolkit/compare/<old commit>..main
+```

CONTRIBUTING.md

@@ -21,7 +21,7 @@ currently implemented by this tool.
 | ---------------------------------------------------------------------- | -------- |
 | [`@actions/artifact`](https://www.npmjs.com/package/@actions/artifact) | `2.3.2`  |
 | [`@actions/core`](https://www.npmjs.com/package/@actions/core)         | `1.11.1` |
-| [`@actions/github`](https://www.npmjs.com/package/@actions/github)     | `6.0.0`  |
+| [`@actions/github`](https://www.npmjs.com/package/@actions/github)     | `6.0.1`  |
 
 ## Changelog
 

README.md

@@ -3,6 +3,7 @@ import { jest } from '@jest/globals'
 export const debug = jest.fn().mockImplementation(() => {})
 export const error = jest.fn().mockImplementation(() => {})
 export const info = jest.fn().mockImplementation(() => {})
+export const isDebug = jest.fn().mockImplementation(() => false)
 export const getInput = jest.fn().mockImplementation(() => {})
 export const setOutput = jest.fn().mockImplementation(() => {})
 export const setFailed = jest.fn().mockImplementation(() => {})

__fixtures__/@actions/core.ts

@@ -0,0 +1,9 @@
+import { jest } from '@jest/globals'
+
+export const which = jest.fn().mockImplementation(() => {})
+export const mkdirP = jest.fn().mockImplementation(() => {})
+
+export default {
+  which,
+  mkdirP
+}

__fixtures__/@actions/io.ts

@@ -1,21 +1,27 @@
 import { jest } from '@jest/globals'
 
 export const accessSync = jest.fn()
+export const copyFileSync = jest.fn()
 export const createWriteStream = jest.fn()
 export const createReadStream = jest.fn()
 export const existsSync = jest.fn()
 export const mkdirSync = jest.fn()
+export const readdirSync = jest.fn()
 export const readFileSync = jest.fn()
 export const rmSync = jest.fn()
 export const statSync = jest.fn()
+export const writeFileSync = jest.fn()
 
 export default {
   accessSync,
+  copyFileSync,
   createWriteStream,
   createReadStream,
   existsSync,
   mkdirSync,
+  readdirSync,
   readFileSync,
   rmSync,
-  statSync
+  statSync,
+  writeFileSync
 }

__fixtures__/fs.ts

@@ -67,6 +67,7 @@ const { DefaultArtifactClient } = await import(
 describe('DefaultArtifactClient', () => {
   beforeEach(() => {
     // Set environment variables
+    process.env.LOCAL_ACTION_WORKSPACE = '/tmp/artifacts'
     process.env.LOCAL_ACTION_ARTIFACT_PATH = '/tmp/artifacts'
 
     // Reset metadata
@@ -80,10 +81,23 @@ describe('DefaultArtifactClient', () => {
     jest.resetAllMocks()
 
     // Unset environment variables
+    delete process.env.LOCAL_ACTION_WORKSPACE
     delete process.env.LOCAL_ACTION_ARTIFACT_PATH
   })
 
   describe('uploadArtifact', () => {
+    it('Throws if LOCAL_ACTION_WORKSPACE is not set', async () => {
+      delete process.env.LOCAL_ACTION_WORKSPACE
+
+      const client = new DefaultArtifactClient()
+
+      await expect(
+        client.uploadArtifact('artifact-name', ['file1', 'file2'], 'root')
+      ).rejects.toThrow(
+        'LOCAL_ACTION_WORKSPACE must be set when interacting with @actions/artifact!'
+      )
+    })
+
     it('Throws if LOCAL_ACTION_ARTIFACT_PATH is not set', async () => {
       delete process.env.LOCAL_ACTION_ARTIFACT_PATH
 
@@ -114,6 +128,16 @@ describe('DefaultArtifactClient', () => {
   })
 
   describe('downloadArtifact', () => {
+    it('Throws if LOCAL_ACTION_WORKSPACE is not set', async () => {
+      delete process.env.LOCAL_ACTION_WORKSPACE
+
+      const client = new DefaultArtifactClient()
+
+      await expect(client.downloadArtifact(1)).rejects.toThrow(
+        'LOCAL_ACTION_WORKSPACE must be set when interacting with @actions/artifact!'
+      )
+    })
+
     it('Throws if LOCAL_ACTION_ARTIFACT_PATH is not set', async () => {
       delete process.env.LOCAL_ACTION_ARTIFACT_PATH
 
@@ -157,6 +181,16 @@ describe('DefaultArtifactClient', () => {
   })
 
   describe('listArtifacts', () => {
+    it('Throws if LOCAL_ACTION_WORKSPACE is not set', async () => {
+      delete process.env.LOCAL_ACTION_WORKSPACE
+
+      const client = new DefaultArtifactClient()
+
+      await expect(client.listArtifacts()).rejects.toThrow(
+        'LOCAL_ACTION_WORKSPACE must be set when interacting with @actions/artifact!'
+      )
+    })
+
     it('Throws if LOCAL_ACTION_ARTIFACT_PATH is not set', async () => {
       delete process.env.LOCAL_ACTION_ARTIFACT_PATH
 
@@ -200,6 +234,16 @@ describe('DefaultArtifactClient', () => {
   })
 
   describe('getArtifact', () => {
+    it('Throws if LOCAL_ACTION_WORKSPACE is not set', async () => {
+      delete process.env.LOCAL_ACTION_WORKSPACE
+
+      const client = new DefaultArtifactClient()
+
+      await expect(client.getArtifact('artifact-name')).rejects.toThrow(
+        'LOCAL_ACTION_WORKSPACE must be set when interacting with @actions/artifact!'
+      )
+    })
+
     it('Throws if LOCAL_ACTION_ARTIFACT_PATH is not set', async () => {
       delete process.env.LOCAL_ACTION_ARTIFACT_PATH
 
@@ -243,6 +287,16 @@ describe('DefaultArtifactClient', () => {
   })
 
   describe('deleteArtifact', () => {
+    it('Throws if LOCAL_ACTION_WORKSPACE is not set', async () => {
+      delete process.env.LOCAL_ACTION_WORKSPACE
+
+      const client = new DefaultArtifactClient()
+
+      await expect(client.deleteArtifact('artifact-name')).rejects.toThrow(
+        'LOCAL_ACTION_WORKSPACE must be set when interacting with @actions/artifact!'
+      )
+    })
+
     it('Throws if LOCAL_ACTION_ARTIFACT_PATH is not set', async () => {
       delete process.env.LOCAL_ACTION_ARTIFACT_PATH