@ronaldphilipsen/local-action 0.0.0-stage → 7.1.0

package/src/stubs/artifact/internal/shared/config.ts

@@ -0,0 +1,64 @@
+/**
+ * Last Reviewed Commit: 02afeb157764304bb3bfe1a6cfd37258ec3fcf7c
+ * Last Reviewed Date: 2026-01-16
+ *
+ * @remarks
+ *
+ * - Removed getConcurrency
+ * - Removed getUploadChunkTimeout
+ */
+
+/**
+ * Used for controlling the highWaterMark value of the zip that is being
+ * streamed. The same value is used as the chunk size that is use during upload
+ * to blob storage
+ */
+export function getUploadChunkSize(): number {
+  return 8 * 1024 * 1024 // 8 MB Chunks
+}
+
+/**
+ * Checks if the current environment is a GitHub Enterprise Server instance
+ *
+ * @returns True if running on GHES
+ */
+export function isGhes(): boolean {
+  const ghUrl = new URL(process.env.GITHUB_SERVER_URL || 'https://github.com')
+
+  const hostname = ghUrl.hostname.trimEnd().toUpperCase()
+  const isGitHubHost = hostname === 'GITHUB.COM'
+  const isGheHost = hostname.endsWith('.GHE.COM')
+  const isLocalHost = hostname.endsWith('.LOCALHOST')
+
+  return !isGitHubHost && !isGheHost && !isLocalHost
+}
+
+/**
+ * Gets the GitHub workspace directory
+ *
+ * @remarks
+ *
+ * - Modified to use process.cwd() as a fallback
+ *
+ * @returns GitHub workspace directory
+ */
+export function getGitHubWorkspaceDir(): string {
+  return process.env.GITHUB_WORKSPACE || process.cwd()
+}
+
+/**
+ * This value can be changed with ACTIONS_ARTIFACT_MAX_ARTIFACT_COUNT variable.
+ * Defaults to 1000 as a safeguard for rate limiting.
+ */
+export function getMaxArtifactListCount(): number {
+  const maxCountVar = process.env.ACTIONS_ARTIFACT_MAX_ARTIFACT_COUNT || '1000'
+
+  const maxCount = parseInt(maxCountVar)
+  if (isNaN(maxCount) || maxCount < 1) {
+    throw new Error(
+      'Invalid value set for ACTIONS_ARTIFACT_MAX_ARTIFACT_COUNT env variable'
+    )
+  }
+
+  return maxCount
+}

package/src/stubs/artifact/internal/shared/errors.ts

@@ -0,0 +1,53 @@
+/**
+ * Last Reviewed Commit: 16b786a545a0b3a90e4dc4330af7225cf06f7e93
+ * Last Reviewed Date: 2026-01-16
+ */
+
+/**
+ * Files Not Found Error
+ */
+export class FilesNotFoundError extends Error {
+  files: string[]
+
+  constructor(files: string[] = []) {
+    let message = 'No files were found to upload'
+
+    if (files.length > 0) message += `: ${files.join(', ')}`
+
+    super(message)
+    this.files = files
+    this.name = 'FilesNotFoundError'
+  }
+}
+
+/**
+ * Invalid Response Error
+ */
+export class InvalidResponseError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'InvalidResponseError'
+  }
+}
+
+/**
+ * Artifact Not Found Error
+ */
+export class ArtifactNotFoundError extends Error {
+  constructor(message = 'Artifact not found') {
+    super(message)
+    this.name = 'ArtifactNotFoundError'
+  }
+}
+
+/**
+ * GHES Not Supported Error
+ */
+export class GHESNotSupportedError extends Error {
+  constructor(
+    message = '@actions/artifact v2.0.0+, upload-artifact@v4+ and download-artifact@v4+ are not currently supported on GHES.'
+  ) {
+    super(message)
+    this.name = 'GHESNotSupportedError'
+  }
+}

package/src/stubs/artifact/internal/shared/interfaces.ts

@@ -0,0 +1,195 @@
+/**
+ * Last Reviewed Commit: d7ddca4309f83d679cb59391635b94e2dfbc40fb
+ * Last Reviewed Date: 2026-01-16
+ */
+
+/**
+ * Response from the server when an artifact is uploaded
+ */
+export interface UploadArtifactResponse {
+  /**
+   * Total size of the artifact in bytes. Not provided if no artifact was
+   * uploaded
+   */
+  size?: number
+  /**
+   * The id of the artifact that was created. Not provided if no artifact was
+   * uploaded. This ID can be used as input to other APIs to download, delete or
+   * get more information about an artifact:
+   * https://docs.github.com/en/rest/actions/artifacts
+   */
+  id?: number
+  /**
+   * The SHA256 digest of the artifact that was created. Not provided if no
+   * artifact was uploaded
+   */
+  digest?: string
+}
+
+/**
+ * Options for uploading an artifact
+ */
+export interface UploadArtifactOptions {
+  /**
+   * Duration after which artifact will expire in days.
+   *
+   * By default artifact expires after 90 days:
+   * https://docs.github.com/en/actions/configuring-and-managing-workflows/persisting-workflow-data-using-artifacts#downloading-and-deleting-artifacts-after-a-workflow-run-is-complete
+   *
+   * Use this option to override the default expiry.
+   *
+   * Min value: 1
+   * Max value: 90 unless changed by repository setting
+   *
+   * If this is set to a greater value than the retention settings allowed, the
+   * retention on artifacts will be reduced to match the max value allowed on
+   * server, and the upload process will continue. An input of 0 assumes default
+   * retention setting.
+   */
+  retentionDays?: number
+  /**
+   * The level of compression for Zlib to be applied to the artifact archive.
+   * The value can range from 0 to 9:
+   * - 0: No compression
+   * - 1: Best speed
+   * - 6: Default compression (same as GNU Gzip)
+   * - 9: Best compression
+   * Higher levels will result in better compression, but will take longer to
+   * complete. For large files that are not easily compressed, a value of 0 is
+   * recommended for significantly faster uploads.
+   */
+  compressionLevel?: number
+}
+
+/**
+ * Response from the server when getting an artifact
+ */
+export interface GetArtifactResponse {
+  /**
+   * Metadata about the artifact that was found
+   */
+  artifact: Artifact
+}
+
+/**
+ * Options for listing artifacts
+ */
+export interface ListArtifactsOptions {
+  /**
+   * Filter the workflow run's artifacts to the latest by name. In the case of
+   * reruns, this can be useful to avoid duplicates.
+   */
+  latest?: boolean
+}
+
+/**
+ * Response from the server when listing artifacts
+ */
+export interface ListArtifactsResponse {
+  /**
+   * A list of artifacts that were found
+   */
+  artifacts: Artifact[]
+}
+
+/**
+ * Response from the server when downloading an artifact
+ */
+export interface DownloadArtifactResponse {
+  /**
+   * The path where the artifact was downloaded to
+   */
+  downloadPath?: string
+  /**
+   * Returns true if the digest of the downloaded artifact does not match the
+   * expected hash
+   */
+  digestMismatch?: boolean
+}
+
+/**
+ * Options for downloading an artifact
+ */
+export interface DownloadArtifactOptions {
+  /**
+   * Denotes where the artifact will be downloaded to. If not specified then the
+   * artifact is download to GITHUB_WORKSPACE
+   */
+  path?: string
+  /**
+   * The hash that was computed for the artifact during upload. If provided, the
+   * outcome of the download will provide a digestMismatch property indicating
+   * whether the hash of the downloaded artifact matches the expected hash.
+   */
+  expectedHash?: string
+}
+
+export interface StreamExtractResponse {
+  /**
+   * The SHA256 hash of the downloaded file
+   */
+  sha256Digest?: string
+}
+
+/**
+ * An Actions Artifact
+ */
+export interface Artifact {
+  /**
+   * The name of the artifact
+   */
+  name: string
+  /**
+   * The ID of the artifact
+   */
+  id: number
+  /**
+   * The size of the artifact in bytes
+   */
+  size: number
+  /**
+   * The time when the artifact was created
+   */
+  createdAt?: Date
+  /**
+   * The digest of the artifact, computed at time of upload.
+   */
+  digest?: string
+}
+
+/**
+ * FindOptions are for fetching Artifact(s) out of the scope of the current run.
+ */
+export interface FindOptions {
+  /**
+   * The criteria for finding Artifact(s) out of the scope of the current run.
+   */
+  findBy?: {
+    /**
+     * Token with actions:read permissions
+     */
+    token: string
+    /**
+     * WorkflowRun of the artifact(s) to lookup
+     */
+    workflowRunId: number
+    /**
+     * Repository owner (eg. 'actions')
+     */
+    repositoryOwner: string
+    /**
+     * Repository owner (eg. 'toolkit')
+     */
+    repositoryName: string
+  }
+}
+
+/**
+ * Response from the server when deleting an artifact
+ */
+export interface DeleteArtifactResponse {
+  /**
+   * The id of the artifact that was deleted
+   */
+  id: number
+}

package/src/stubs/artifact/internal/shared/user-agent.ts

@@ -0,0 +1,13 @@
+/**
+ * Last Reviewed Commit: 4b6a4d80e13a01ecbf41e39098883d69cb54c0d3
+ * Last Reviewed Date: 2026-01-16
+ */
+
+/**
+ * Creates a user agent string for the GitHub client
+ *
+ * @returns User Agent
+ */
+export function getUserAgentString(): string {
+  return `@ronaldphilipsen/local-action-${process.env.npm_package_version}`
+}

package/src/stubs/artifact/internal/upload/path-and-artifact-name-validation.ts

@@ -0,0 +1,92 @@
+/**
+ * Last Reviewed Commit: 7da3ac6edad34a891be2c261a6eb4d74a9843fbc
+ * Last Reviewed Date: 2026-01-16
+ */
+
+import { info } from '../../../core/core.js'
+
+/**
+ * Invalid characters that cannot be in the artifact name or an uploaded file.
+ * Will be rejected from the server if attempted to be sent over. These
+ * characters are not allowed due to limitations with certain file systems such
+ * as NTFS. To maintain platform-agnostic behavior, all characters that are not
+ * supported by an individual filesystem/platform will not be supported on all
+ * fileSystems/platforms
+ *
+ * FilePaths can include characters such as \ and / which are not permitted in
+ * the artifact name alone
+ */
+/* istanbul ignore next */
+const invalidArtifactFilePathCharacters = new Map<string, string>([
+  ['"', ' Double quote "'],
+  [':', ' Colon :'],
+  ['<', ' Less than <'],
+  ['>', ' Greater than >'],
+  ['|', ' Vertical bar |'],
+  ['*', ' Asterisk *'],
+  ['?', ' Question mark ?'],
+  ['\r', ' Carriage return \\r'],
+  ['\n', ' Line feed \\n']
+])
+
+/* istanbul ignore next */
+const invalidArtifactNameCharacters = new Map<string, string>([
+  ...invalidArtifactFilePathCharacters,
+  ['\\', ' Backslash \\'],
+  ['/', ' Forward slash /']
+])
+
+/**
+ * Validates the name of the artifact
+ *
+ * @param name Artifact Name
+ */
+export function validateArtifactName(name: string): void {
+  if (!name)
+    throw new Error(`Provided artifact name input during validation is empty`)
+
+  for (const [
+    invalidCharacterKey,
+    errorMessageForCharacter
+  ] of invalidArtifactNameCharacters) {
+    if (name.includes(invalidCharacterKey))
+      throw new Error(
+        `The artifact name is not valid: ${name}. Contains the following character: ${errorMessageForCharacter}
+          
+Invalid characters include: ${Array.from(
+          invalidArtifactNameCharacters.values()
+        ).toString()}
+          
+These characters are not allowed in the artifact name due to limitations with certain file systems such as NTFS. To maintain file system agnostic behavior, these characters are intentionally not allowed to prevent potential problems with downloads on different file systems.`
+      )
+  }
+
+  info(`Artifact name is valid!`)
+}
+
+/**
+ * Validates file paths
+ *
+ * @param path File Path
+ */
+export function validateFilePath(path: string): void {
+  if (!path)
+    throw new Error(`Provided file path input during validation is empty`)
+
+  for (const [
+    invalidCharacterKey,
+    errorMessageForCharacter
+  ] of invalidArtifactFilePathCharacters) {
+    if (path.includes(invalidCharacterKey))
+      throw new Error(
+        `The path for one of the files in artifact is not valid: ${path}. Contains the following character: ${errorMessageForCharacter}
+          
+Invalid characters include: ${Array.from(
+          invalidArtifactFilePathCharacters.values()
+        ).toString()}
+          
+The following characters are not allowed in files that are uploaded due to limitations with certain file systems such as NTFS. To maintain file system agnostic behavior, these characters are intentionally not allowed to prevent potential problems with downloads on different file systems.
+          `
+      )
+  }
+}

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

@@ -0,0 +1,127 @@
+/**
+ * Last Reviewed Commit: 1e0c16f0dc67246ccb8005965c289aba4114bd56
+ * Last Reviewed Date: 2026-01-16
+ */
+
+import crypto from 'crypto'
+import fs from 'fs'
+import path from 'path'
+import { finished } from 'stream/promises'
+import { EnvMeta } from '../../../../stubs/env.js'
+import * as core from '../../../core/core.js'
+import { FilesNotFoundError, InvalidResponseError } from '../shared/errors.js'
+import type {
+  Artifact,
+  UploadArtifactOptions,
+  UploadArtifactResponse
+} from '../shared/interfaces.js'
+import { validateArtifactName } from './path-and-artifact-name-validation.js'
+import {
+  type UploadZipSpecification,
+  getUploadZipSpecification,
+  validateRootDirectory
+} from './upload-zip-specification.js'
+import { createZipUploadStream } from './zip.js'
+
+/**
+ * Uploads an artifact.
+ *
+ * @remarks
+ *
+ * - Does not upload any artifacts. All artifacts are compressed and saved to
+ *   the local filesystem.
+ *
+ * @param name Name
+ * @param files Files
+ * @param rootDirectory Root Directory
+ * @param options Upload Artifact Options
+ * @returns Upload Artifact Response
+ */
+export async function uploadArtifact(
+  name: string,
+  files: string[],
+  rootDirectory: string,
+  options?: UploadArtifactOptions | undefined
+): Promise<UploadArtifactResponse> {
+  validateArtifactName(name)
+  validateRootDirectory(rootDirectory)
+
+  const zipSpecification: UploadZipSpecification[] = getUploadZipSpecification(
+    files,
+    rootDirectory
+  )
+  /* istanbul ignore next */
+  if (zipSpecification.length === 0)
+    throw new FilesNotFoundError(
+      zipSpecification.flatMap(s => (s.sourcePath ? [s.sourcePath] : []))
+    )
+
+  // Multiple artifacts cannot have the same name.
+  if (EnvMeta.artifacts.some(a => a.name === name))
+    throw new Error(`An artifact with the name ${name} already exists`)
+
+  // Only 10 artifacts can be created in a single job.
+  if (EnvMeta.artifacts.length >= 10)
+    throw new Error('Maximum number of artifacts (10) created')
+
+  // Create the artifact metadata
+  const artifact: Artifact = {
+    name,
+    id: EnvMeta.artifacts.length + 1,
+    size: 0,
+    createdAt: new Date()
+  }
+
+  const response: UploadArtifactResponse = {
+    size: 0,
+    id: artifact.id,
+    digest: ''
+  }
+
+  const zipUploadStream = await createZipUploadStream(
+    zipSpecification,
+    options?.compressionLevel
+  )
+
+  const writeStream = fs.createWriteStream(
+    path.join(process.env.LOCAL_ACTION_ARTIFACT_PATH!, `${artifact.name}.zip`)
+  )
+  const hashStream = crypto.createHash('sha256')
+
+  /* istanbul ignore next */
+  writeStream
+    .on('error', error => {
+      throw error
+    })
+    .on('finish', () => {
+      try {
+        core.info(`Finalizing artifact upload`)
+        EnvMeta.artifacts.push(artifact)
+        core.info(
+          `Artifact ${artifact.name}.zip successfully finalized. Artifact ID ${artifact.id}`
+        )
+
+        response.size = artifact.size
+      } catch (error: any) {
+        core.debug(`Artifact creation failed: ${error}`)
+        throw new InvalidResponseError(
+          'CreateArtifact: response from backend was not ok'
+        )
+      }
+    })
+
+  /* istanbul ignore next */
+  zipUploadStream
+    .on('data', chunk => {
+      artifact.size += chunk.length
+    })
+    .pipe(writeStream)
+  zipUploadStream.pipe(hashStream).setEncoding('hex')
+
+  await finished(writeStream)
+
+  hashStream.end()
+  response.digest = hashStream.read()
+
+  return response
+}

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

@@ -0,0 +1,108 @@
+/**
+ * Last Reviewed Commit: 7f19a7886a8b3b16c971a89cb787b850cb6a7980
+ * Last Reviewed Date: 2026-01-16
+ */
+
+import * as fs from 'fs'
+import { normalize, resolve } from 'path'
+import * as core from '../../../core/core.js'
+import { validateFilePath } from './path-and-artifact-name-validation.js'
+
+export interface UploadZipSpecification {
+  /**
+   * An absolute source path that points to a file that will be added to a zip.
+   * Null if creating a new directory
+   */
+  sourcePath: string | null
+
+  /**
+   * The destination path in a zip for a file
+   */
+  destinationPath: string
+
+  /**
+   * Information about the file
+   *
+   * https://nodejs.org/api/fs.html#class-fsstats
+   */
+  stats: fs.Stats
+}
+
+/**
+ * Checks if a root directory exists and is valid.
+ *
+ * @param rootDirectory Root Directory
+ */
+export function validateRootDirectory(rootDirectory: string): void {
+  if (!fs.existsSync(rootDirectory))
+    throw new Error(
+      `The provided rootDirectory ${rootDirectory} does not exist`
+    )
+
+  if (!fs.statSync(rootDirectory).isDirectory())
+    throw new Error(
+      `The provided rootDirectory ${rootDirectory} is not a valid directory`
+    )
+
+  core.info(`Root directory input is valid!`)
+}
+
+/**
+ * Creates a specification that describes how a zip file will be created for a
+ * set of input files.
+ *
+ * @param filesToZip Files to Zip
+ * @param rootDirectory Root Directory
+ * @returns Upload Zip Specification
+ */
+/* istanbul ignore next */
+export function getUploadZipSpecification(
+  filesToZip: string[],
+  rootDirectory: string
+): UploadZipSpecification[] {
+  const specification: UploadZipSpecification[] = []
+
+  // Normalize and resolve, this allows for either absolute or relative paths to
+  // be used
+  rootDirectory = normalize(rootDirectory)
+  rootDirectory = resolve(rootDirectory)
+
+  for (let file of filesToZip) {
+    const stats = fs.lstatSync(file, { throwIfNoEntry: false })
+    if (!stats) throw new Error(`File ${file} does not exist`)
+
+    if (!stats.isDirectory()) {
+      // Normalize and resolve, this allows for either absolute or relative
+      // paths to be used
+      file = normalize(file)
+      file = resolve(file)
+
+      if (!file.startsWith(rootDirectory))
+        throw new Error(
+          `The rootDirectory: ${rootDirectory} is not a parent directory of the file: ${file}`
+        )
+
+      // Check for forbidden characters in file paths that may cause ambiguous
+      // behavior if downloaded on different file systems
+      const uploadPath = file.replace(rootDirectory, '')
+      validateFilePath(uploadPath)
+
+      specification.push({
+        sourcePath: file,
+        destinationPath: uploadPath,
+        stats
+      })
+    } else {
+      // Empty directory
+      const directoryPath = file.replace(rootDirectory, '')
+      validateFilePath(directoryPath)
+
+      specification.push({
+        sourcePath: null,
+        destinationPath: directoryPath,
+        stats
+      })
+    }
+  }
+  return specification
+}