@ronaldphilipsen/local-action 0.0.0-stage → 7.0.1

package/src/stubs/artifact/internal/upload/zip.ts

@@ -0,0 +1,122 @@
+/**
+ * Last Reviewed Commit: https://github.com/actions/toolkit/blob/ee91adfbc4f4d1470e176a8d568c0cbdabaf98e0/packages/artifact/src/internal/upload/zip.ts
+ * Last Reviewed Date: 2026-01-16
+ */
+
+import archiver from 'archiver'
+import { realpath } from 'fs/promises'
+import * as stream from 'stream'
+import * as core from '../../../core/core.js'
+import { getUploadChunkSize } from '../shared/config.js'
+import type { UploadZipSpecification } from './upload-zip-specification.js'
+
+/* istanbul ignore next */
+export const DEFAULT_COMPRESSION_LEVEL = 6
+
+// Custom stream transformer so we can set the highWaterMark property
+// See https://github.com/nodejs/node/issues/8855
+/* istanbul ignore next */
+export class ZipUploadStream extends stream.Transform {
+  constructor(bufferSize: number) {
+    super({
+      highWaterMark: bufferSize
+    })
+  }
+
+  _transform(chunk: any, enc: any, cb: any): void {
+    cb(null, chunk)
+  }
+}
+
+/**
+ * Creates a zip upload stream.
+ *
+ * @param uploadSpecification Upload Specification
+ * @param compressionLevel Compression Level
+ * @returns Zip Upload Stream
+ */
+/* istanbul ignore next */
+export async function createZipUploadStream(
+  uploadSpecification: UploadZipSpecification[],
+  compressionLevel: number = DEFAULT_COMPRESSION_LEVEL
+): Promise<ZipUploadStream> {
+  core.debug(
+    `Creating Artifact archive with compressionLevel: ${compressionLevel}`
+  )
+
+  const zip = archiver.create('zip', {
+    highWaterMark: getUploadChunkSize(),
+    zlib: { level: compressionLevel }
+  })
+
+  // register callbacks for various events during the zip lifecycle
+  zip.on('error', zipErrorCallback)
+  zip.on('warning', zipWarningCallback)
+  zip.on('finish', zipFinishCallback)
+  zip.on('end', zipEndCallback)
+
+  for (const file of uploadSpecification) {
+    if (file.sourcePath !== null) {
+      // Check if symlink and resolve the source path
+      let sourcePath = file.sourcePath
+      if (file.stats.isSymbolicLink())
+        sourcePath = await realpath(file.sourcePath)
+
+      // Add the file to the zip
+      zip.file(sourcePath, {
+        name: file.destinationPath
+      })
+    } else {
+      // Add a directory to the zip
+      zip.append('', { name: file.destinationPath })
+    }
+  }
+
+  const bufferSize = getUploadChunkSize()
+  const zipUploadStream = new ZipUploadStream(bufferSize)
+
+  core.debug(
+    `Zip write high watermark value ${zipUploadStream.writableHighWaterMark}`
+  )
+  core.debug(
+    `Zip read high watermark value ${zipUploadStream.readableHighWaterMark}`
+  )
+
+  zip.pipe(zipUploadStream)
+  zip.finalize()
+
+  return zipUploadStream
+}
+
+/* istanbul ignore next */
+const zipErrorCallback = (error: any): void => {
+  core.error('An error has occurred while creating the zip file for upload')
+  core.info(error)
+
+  throw new Error('An error has occurred during zip creation for the artifact')
+}
+
+/* istanbul ignore next */
+const zipWarningCallback = (error: any): void => {
+  if (error.code === 'ENOENT') {
+    core.warning(
+      'ENOENT warning during artifact zip creation. No such file or directory'
+    )
+    core.info(error)
+  } else {
+    core.warning(
+      `A non-blocking warning has occurred during artifact zip creation: ${error.code}`
+    )
+    core.info(error)
+  }
+}
+
+/* istanbul ignore next */
+const zipFinishCallback = (): void => {
+  core.debug('Zip stream for upload has finished.')
+}
+
+/* istanbul ignore next */
+const zipEndCallback = (): void => {
+  core.debug('Zip stream for upload has ended.')
+}

package/src/stubs/cache/cache.ts

@@ -0,0 +1,334 @@
+/**
+ * Last Reviewed Commit: 06f7fd9df15088233d2593af69ea710eb2fc516b
+ * Last Reviewed Date: 2026-01-16
+ */
+
+import * as core from '@actions/core'
+import * as fs from 'fs'
+import * as path from 'path'
+import { EnvMeta } from '../env.js'
+import { ReserveCacheError, ValidationError } from './errors.js'
+import * as utils from './internal/cacheUtils.js'
+import { createTar, extractTar, listTar } from './internal/tar.js'
+import { DownloadOptions, UploadOptions } from './options.js'
+
+export const CACHE_STUBS = {
+  restoreCache,
+  saveCache
+}
+
+/**
+ * Validates at least one path is provided.
+ *
+ * @param paths List of paths to check
+ */
+/* istanbul ignore next */
+function checkPaths(paths: string[]): void {
+  if (!paths || paths.length === 0)
+    throw new ValidationError(
+      `Path Validation Error: At least one directory or file path is required`
+    )
+}
+
+/**
+ * Validates the provided key is sufficient length and contains valid characters
+ *
+ * @param key Key to check
+ */
+/* istanbul ignore next */
+function checkKey(key: string): void {
+  if (key.length > 512)
+    throw new ValidationError(
+      `Key Validation Error: ${key} cannot be larger than 512 characters.`
+    )
+
+  const regex = /^[^,]*$/
+
+  if (!regex.test(key))
+    throw new ValidationError(
+      `Key Validation Error: ${key} cannot contain commas.`
+    )
+}
+
+/**
+ * Restores cache from keys
+ *
+ * @param paths List of file paths to restore from the cache
+ * @param primaryKey Explicit key for restoring the cache. Lookup is done with prefix matching.
+ * @param restoreKeys Optional ordered list of keys to use for restoring the cache if no cache hit occurred for primaryKey
+ * @param downloadOptions Cache download options
+ * @param enableCrossOsArchive Optional boolean enabled to restore on Windows any cache created on any platform
+ * @returns Key for the cache hit, otherwise undefined
+ *
+ * @remarks
+ *
+ * - Checks for required environment variables.
+ * - Caches are only managed locally...removed check for service version.
+ */
+export async function restoreCache(
+  paths: string[],
+  primaryKey: string,
+  restoreKeys?: string[],
+  options?: DownloadOptions,
+  enableCrossOsArchive = false
+): Promise<string | undefined> {
+  if (!process.env.LOCAL_ACTION_WORKSPACE)
+    throw new Error(
+      'LOCAL_ACTION_WORKSPACE must be set when interacting with @actions/cache!'
+    )
+  if (!process.env.LOCAL_ACTION_CACHE_PATH)
+    throw new Error(
+      'LOCAL_ACTION_CACHE_PATH must be set when interacting with @actions/cache!'
+    )
+
+  checkPaths(paths)
+
+  return await restoreCacheFromFilesystem(
+    paths,
+    primaryKey,
+    restoreKeys,
+    options,
+    enableCrossOsArchive
+  )
+}
+
+/**
+ * Restores cache from local filesystem
+ *
+ * @param paths List of file paths to restore from the cache
+ * @param primaryKey Explicit key for restoring the cache. Lookup is done with prefix matching
+ * @param restoreKeys Optional ordered list of keys to use for restoring the cache if no cache hit occurred for primaryKey
+ * @param downloadOptions Cache download options
+ * @param enableCrossOsArchive Optional boolean enabled to restore on Windows any cache created on any platform
+ * @returns Key for the cache hit, otherwise undefined
+ *
+ * @remarks
+ *
+ * - Replaces v1 and v2 caching implementations.
+ * - Download options, other than `lookupOnly`, are ignored.
+ */
+async function restoreCacheFromFilesystem(
+  paths: string[],
+  primaryKey: string,
+  restoreKeys?: string[],
+  options?: DownloadOptions,
+  /* istanbul ignore next */
+  enableCrossOsArchive = false
+): Promise<string | undefined> {
+  const keys = [primaryKey, ...(restoreKeys ?? [])]
+
+  core.debug('Resolved Keys:')
+  core.debug(JSON.stringify(keys))
+
+  if (keys.length > 10)
+    throw new ValidationError(
+      `Key Validation Error: Keys are limited to a maximum of 10.`
+    )
+
+  for (const key of keys) checkKey(key)
+
+  let archivePath: string
+  let matchedKey = undefined
+  let matchedCache = undefined
+
+  try {
+    const compressionMethod = await utils.getCompressionMethod()
+    const cacheVersion = utils.getCacheVersion(
+      paths,
+      compressionMethod,
+      enableCrossOsArchive
+    )
+
+    const caches = fs
+      .readdirSync(process.env.LOCAL_ACTION_CACHE_PATH!)
+      .filter(file => file.endsWith('.cache'))
+      .map(file => file.replace('.cache', ''))
+
+    // Check the caches for a matching key
+    for (const key of keys) {
+      const cache = caches.find(c => c === key || c.startsWith(key))
+
+      if (cache) {
+        matchedKey = key
+        matchedCache = cache
+        break
+      }
+    }
+
+    if (matchedCache === undefined) {
+      core.debug(
+        `Cache not found for version ${cacheVersion} of keys: ${keys.join(
+          ', '
+        )}`
+      )
+
+      return undefined
+    }
+
+    if (primaryKey !== matchedKey)
+      core.info(`Cache hit for restore-key: ${matchedKey}`)
+    else core.info(`Cache hit for: ${matchedKey}`)
+
+    if (options?.lookupOnly) {
+      core.info('Lookup only - skipping download')
+      return matchedKey
+    }
+
+    archivePath = path.join(
+      process.env.LOCAL_ACTION_CACHE_PATH!,
+      `${matchedCache}.cache`
+    )
+    core.debug(`Archive path: ${archivePath}`)
+
+    const archiveFileSize = utils.getArchiveFileSizeInBytes(archivePath)
+    core.info(
+      `Cache Size: ~${Math.round(
+        archiveFileSize / (1024 * 1024)
+      )} MB (${archiveFileSize} B)`
+    )
+
+    if (core.isDebug()) await listTar(archivePath, compressionMethod)
+    await extractTar(archivePath, compressionMethod)
+
+    core.info('Cache restored successfully')
+    return matchedKey
+  } catch (error: any) {
+    core.warning(`Failed to restore: ${error.message}`)
+  }
+
+  return undefined
+}
+
+/**
+ * Saves a list of files with the specified key
+ *
+ * @param paths List of file paths to be cached
+ * @param key Explicit key for restoring the cache
+ * @param enableCrossOsArchive Optional boolean enabled to save cache on Windows which could be restored on any platform
+ * @param options Cache upload options
+ * @returns Cache ID if the cache was saved successfully
+ * @throws Error if save fails
+ *
+ * @remarks
+ *
+ * - Checks for required environment variables.
+ * - Caches are only managed locally...removed check for service version.
+ */
+/* istanbul ignore next */
+export async function saveCache(
+  paths: string[],
+  key: string,
+  options?: UploadOptions,
+  enableCrossOsArchive = false
+): Promise<number> {
+  if (!process.env.LOCAL_ACTION_WORKSPACE)
+    throw new Error(
+      'LOCAL_ACTION_WORKSPACE must be set when interacting with @actions/cache!'
+    )
+  if (!process.env.LOCAL_ACTION_CACHE_PATH)
+    throw new Error(
+      'LOCAL_ACTION_CACHE_PATH must be set when interacting with @actions/cache!'
+    )
+
+  checkPaths(paths)
+  checkKey(key)
+
+  return await saveCacheToFilesystem(paths, key, options, enableCrossOsArchive)
+}
+
+/**
+ * Saves cache to local filesystem
+ *
+ * @param paths List of file paths to be cached
+ * @param key Explicit key for restoring the cache
+ * @param options Cache upload options
+ * @param enableCrossOsArchive Optional boolean enabled to save cache on Windows which could be restored on any platform
+ * @returns Cache ID if the cache was saved successfully
+ *
+ * @remarks
+ *
+ * - Replaces v1 and v2 caching implementations.
+ * - Azure SDK settings and upload options are ignored.
+ * - Cache reserving is replaced with file conflict checks.
+ */
+async function saveCacheToFilesystem(
+  paths: string[],
+  key: string,
+  options?: UploadOptions,
+  /* istanbul ignore next */
+  enableCrossOsArchive = false
+): Promise<number> {
+  const compressionMethod = await utils.getCompressionMethod()
+  const cachePaths = await utils.resolvePaths(paths)
+
+  core.debug('Cache Paths:')
+  core.debug(`${JSON.stringify(cachePaths)}`)
+
+  if (cachePaths.length === 0)
+    throw new Error(
+      `Path Validation Error: Path(s) specified in the action for caching do(es) not exist, hence no cache is being saved.`
+    )
+
+  const archiveFolder = await utils.createTempDirectory()
+  const archivePath = path.join(
+    archiveFolder,
+    utils.getCacheFileName(compressionMethod)
+  )
+
+  core.debug(`Archive Path: ${archivePath}`)
+
+  try {
+    await createTar(archiveFolder, cachePaths, compressionMethod)
+
+    if (core.isDebug()) await listTar(archivePath, compressionMethod)
+
+    const archiveSizeBytes = utils.getArchiveFileSizeInBytes(archivePath)
+    core.debug(`File Size: ${archiveSizeBytes}`)
+
+    // Attempt to reserve the cache. In local-action, this is done by checking
+    // if there is an existing file with the same name. If so, we fail the save.
+    core.debug('Reserving Cache')
+    const version = utils.getCacheVersion(
+      paths,
+      compressionMethod,
+      enableCrossOsArchive
+    )
+
+    if (
+      fs.existsSync(
+        path.join(
+          process.env.LOCAL_ACTION_CACHE_PATH!,
+          `${key}-${version}.cache`
+        )
+      )
+    )
+      throw new ReserveCacheError(
+        `Unable to reserve cache with key ${key}, another job may be creating this cache.`
+      )
+
+    // Copy the archive to the cache folder. In local-action, this is simply
+    // copying the file.
+    core.debug(`Attempting to upload cache located at: ${archivePath}`)
+    fs.copyFileSync(
+      archivePath,
+      path.join(process.env.LOCAL_ACTION_CACHE_PATH!, `${key}-${version}.cache`)
+    )
+
+    // Generate a cache ID. This can just be the next available ID based on
+    // existing caches.
+    return (
+      Math.max(...Object.keys(EnvMeta.caches).map(key => parseInt(key))) + 1
+    )
+  } catch (error: any) {
+    core.warning(`Failed to save: ${error.message}`)
+  } finally {
+    // Try to delete the original archive to save space
+    try {
+      await utils.unlinkFile(archivePath)
+    } catch (error) {
+      core.debug(`Failed to delete archive: ${error}`)
+    }
+  }
+
+  return -1
+}

package/src/stubs/cache/errors.ts

@@ -0,0 +1,31 @@
+/**
+ * Caching validation error
+ */
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ValidationError'
+    Object.setPrototypeOf(this, ValidationError.prototype)
+  }
+}
+
+/**
+ * Cache reservation error
+ */
+export class ReserveCacheError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ReserveCacheError'
+    Object.setPrototypeOf(this, ReserveCacheError.prototype)
+  }
+}
+
+/**
+ * Invalid response error
+ */
+export class InvalidResponseError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'InvalidResponseError'
+  }
+}

package/src/stubs/cache/interfaces.ts

@@ -0,0 +1,4 @@
+export interface ArchiveTool {
+  path: string
+  type: string
+}

package/src/stubs/cache/internal/cacheUtils.ts

@@ -0,0 +1,207 @@
+/**
+ * Last Reviewed Commit: 267841d7bd659368f7382ca22d5ca0b2af68f0b3
+ * Last Reviewed Date: 2026-01-16
+ *
+ * @remarks
+ *
+ * - Deleted assertDefined function
+ * - Deleted getRuntimeToken function
+ */
+import * as core from '@actions/core'
+import * as exec from '@actions/exec'
+import * as glob from '@actions/glob'
+import * as io from '@actions/io'
+import * as crypto from 'crypto'
+import * as fs from 'fs'
+import * as path from 'path'
+import * as semver from 'semver'
+import * as util from 'util'
+import {
+  CacheFilename,
+  CompressionMethod,
+  GnuTarPathOnWindows
+} from './constants.js'
+
+const versionSalt = '1.0'
+
+/**
+ * Creates a temporary directory and returns the path
+ *
+ * @returns Path to the temporary directory
+ *
+ * @remarks
+ *
+ * - Replaces location with LOCAL_ACTION_WORKSPACE/actions/temp
+ */
+export async function createTempDirectory(): Promise<string> {
+  const tempDirectory = path.join(
+    process.env.LOCAL_ACTION_WORKSPACE!,
+    'actions',
+    'temp'
+  )
+  const dest = path.join(tempDirectory, crypto.randomUUID())
+
+  await io.mkdirP(dest)
+
+  return dest
+}
+
+/**
+ * Gets the size of the archive file in bytes
+ *
+ * @param filePath Path to the archive file
+ * @returns Size of the archive file in bytes
+ */
+/* istanbul ignore next */
+export function getArchiveFileSizeInBytes(filePath: string): number {
+  return fs.statSync(filePath).size
+}
+
+/**
+ * Resolves the paths to be cached
+ *
+ * @param patterns Array of glob patterns
+ * @returns Array of resolved paths
+ */
+/* istanbul ignore next */
+export async function resolvePaths(patterns: string[]): Promise<string[]> {
+  const paths: string[] = []
+  const workspace = process.env['GITHUB_WORKSPACE'] ?? process.cwd()
+  const globber = await glob.create(patterns.join('\n'), {
+    implicitDescendants: false
+  })
+
+  for await (const file of globber.globGenerator()) {
+    const relativeFile = path
+      .relative(workspace, file)
+      .replace(new RegExp(`\\${path.sep}`, 'g'), '/')
+    core.debug(`Matched: ${relativeFile}`)
+
+    // Paths are made relative so the tar entries are all relative to the root
+    // of the workspace.
+    if (relativeFile === '') paths.push('.')
+    else paths.push(`${relativeFile}`)
+  }
+
+  return paths
+}
+
+/**
+ * Deletes a file
+ *
+ * @param filePath Path to the file
+ * @returns Promise that resolves when the file is deleted
+ */
+/* istanbul ignore next */
+export async function unlinkFile(filePath: fs.PathLike): Promise<void> {
+  return util.promisify(fs.unlink)(filePath)
+}
+
+/**
+ * Gets the version of an application by executing it with the provided
+ * arguments
+ *
+ * @param app Application to get the version of
+ * @param additionalArgs Additional arguments to pass to the application
+ * @returns Version of the application
+ */
+/* istanbul ignore next */
+async function getVersion(
+  app: string,
+  additionalArgs: string[] = []
+): Promise<string> {
+  let versionOutput = ''
+  additionalArgs.push('--version')
+  core.debug(`Checking ${app} ${additionalArgs.join(' ')}`)
+
+  try {
+    await exec.exec(`${app}`, additionalArgs, {
+      ignoreReturnCode: true,
+      silent: true,
+      listeners: {
+        stdout: (data: Buffer): string => (versionOutput += data.toString()),
+        stderr: (data: Buffer): string => (versionOutput += data.toString())
+      }
+    })
+  } catch (err: any) {
+    core.debug(err.message)
+  }
+
+  versionOutput = versionOutput.trim()
+  core.debug(versionOutput)
+
+  return versionOutput
+}
+
+/**
+ * Gets the compression method to use when creating caches.
+ *
+ * Use zstandard if possible to maximize cache performance.
+ */
+/* istanbul ignore next */
+export async function getCompressionMethod(): Promise<CompressionMethod> {
+  const versionOutput = await getVersion('zstd', ['--quiet'])
+  const version = semver.clean(versionOutput)
+
+  core.debug(`zstd version: ${version}`)
+
+  if (versionOutput === '') return CompressionMethod.Gzip
+  else return CompressionMethod.ZstdWithoutLong
+}
+
+/**
+ * Gets the cache file name based on the compression method
+ *
+ * @param compressionMethod Compression method
+ * @returns Cache file name
+ */
+/* istanbul ignore next */
+export function getCacheFileName(compressionMethod: CompressionMethod): string {
+  return compressionMethod === CompressionMethod.Gzip
+    ? CacheFilename.Gzip
+    : CacheFilename.Zstd
+}
+
+/**
+ * Gets the path to GNU tar on Windows, if available
+ *
+ * @returns Path to GNU tar on Windows, or empty string if not available
+ */
+/* istanbul ignore next */
+export async function getGnuTarPathOnWindows(): Promise<string> {
+  if (fs.existsSync(GnuTarPathOnWindows)) return GnuTarPathOnWindows
+
+  const versionOutput = await getVersion('tar')
+  return versionOutput.toLowerCase().includes('gnu tar') ? io.which('tar') : ''
+}
+
+/**
+ * Get the cache version
+ *
+ * @param paths Paths included in the cache
+ * @param compressionMethod Compression method
+ * @param enableCrossOsArchive Enable cross OS archive
+ * @returns Cache version
+ */
+/* istanbul ignore next */
+export function getCacheVersion(
+  paths: string[],
+  compressionMethod?: CompressionMethod,
+  enableCrossOsArchive = false
+): string {
+  // don't pass changes upstream
+  const components = paths.slice()
+
+  // Add compression method to cache version to restore
+  // compressed cache as per compression method
+  if (compressionMethod) components.push(compressionMethod)
+
+  // Only check for windows platforms if enableCrossOsArchive is false
+  if (process.platform === 'win32' && !enableCrossOsArchive)
+    components.push('windows-only')
+
+  // Add salt to cache version to support breaking changes in cache entry
+  components.push(versionSalt)
+
+  return crypto.createHash('sha256').update(components.join('|')).digest('hex')
+}