@leverege/build-tools 2.93.0-quinn.8 → 2.93.0

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "editor.formatOnSave": true
+}

package/README.md

@@ -18,7 +18,15 @@ npm install -g @leverege/build-tools
 ```bash
   . `build-tools --bashfun`
 ```
-* **docker-to-registry**: used to build and deploy docker images to the GCP image area
+* **docker-to-registry**: used to build and deploy application docker images to the GCP artifact registry
+* **pull-artifact**: used to pull generic artifacts from the GCP artifact registry
+```bash
+Usage: pull-artifact -f <artifact schema file path> -n <package name> -v <package version>
+```
+* **push-artifact**: used to push generic artifacts to the GCP artifact registry
+```bash
+Usage: push-artifact -f <artifact schema file path> -n <package name> -v <package version>
+```
 
 ### Helm Helpers:
 * **overwhelm**: a k8s context helper and yaml replacer *${REPLACE_ME}*
@@ -57,6 +65,15 @@ Usage: k8scale <up|dn|down|roll> [services]
 * **prune-git**: performs maintenance on a list of git repositories.
 * **pull-git**: walks a list of git repos, pulling each if they are clean.
 
+### Troubleshooting:
+
+For additional debug level logging, set the environment variable `BUILD_TOOLS_DEBUG=1` before running the tool.
+
+Example:
+```bash
+BUILD_TOOLS_DEBUG=1 docker-to-registry
+```
+
 ## Authors
 
 * **DevOps and Friends**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leverege/build-tools",
-  "version": "2.93.0-quinn.8",
+  "version": "2.93.0",
   "description": "A collection of build / support tools for Leverege developers",
   "main": "index.js",
   "repository": {
@@ -11,7 +11,7 @@
     "clean": "rm -rf lib",
     "lint": "find ./src -name \\*.\\*js | xargs npx eslint --report-unused-disable-directives",
     "prepare": "[ $SKIP_PREPARE ] && exit 0 || ./src/hook-and-release.mjs",
-    "test": "echo \"no tests specified\" && exit 0",
+    "test": "mocha -t 60000 --exit 'test/**/*.mjs'",
     "prepack": "npm exec prepack"
   },
   "bin": {
@@ -54,7 +54,9 @@
     "pkglint": "src/pkglint.sh",
     "prepack": "src/prepack.mjs",
     "prune-git": "src/prune-git.sh",
+    "pull-artifact": "src/artifacts/pull-artifact.mjs",
     "pull-git": "src/pull-git.sh",
+    "push-artifact": "src/artifacts/push-artifact.mjs",
     "push-my-chart": "src/push-my-chart.mjs",
     "refresh-npm-token": "src/refresh-npm-token.mjs",
     "refresh-py-idx": "src/refresh-py-idx.sh",
@@ -91,11 +93,14 @@
     "shell-quote": "^1.8.3",
     "simple-git": "^3.30.0",
     "sloc": "^0.3.2",
+    "superstruct": "^2.0.2",
     "toml": "^3.0.0",
     "zx": "^8.8.5"
   },
   "devDependencies": {
     "@leverege/eslint-config-leverege": "^5.1.1",
+    "chai": "^6.2.1",
+    "mocha": "^11.7.5",
     "npm": "^11.6.2"
   }
-}
+}

package/src/Docker.mjs

@@ -121,14 +121,13 @@ const generateDockerfile = async ( options ) => {
     fs.writeFileSync( dockerfilePlugin, dockerfilePluginTemplate )
   }
 
-  const buildDir = options.isYarnProject ? `/tmp/${options.containerName}/build` : './build'
   try {
-    const build = fs.readdirSync( buildDir )
+    const build = fs.readdirSync( './build' )
     if ( build.length === 0 ) {
       errorExit( `***ERROR: the build dir is empty - ${chalk.yellow( 'npm run build' )}` )
     }
   } catch ( err ) {
-    errorExit( `***ERROR: expected the ${buildDir} directory to exist - ${chalk.yellow( 'npm run build' )}` )
+    errorExit( `***ERROR: expected the ./build directory to exist - ${chalk.yellow( 'npm run build' )}` )
   }
 
   // At this point the docker plugin file better exist.
@@ -183,10 +182,8 @@ const buildContainerImage = async ( repoDescr ) => {
     isNodeJsProject,
     isNpmWorkspace,
     isPythonProject,
-    isYarnProject
   } = repoDescr
-  const buildDir = isYarnProject ? `/tmp/${containerName}/build` : './build'
-  const buildWorkspace = `${buildDir}/workspace` // passed to Cloud Build
+  const buildWorkspace = './build/workspace' // passed to Cloud Build
   const imageName = `${artifactRegistry}/images/${containerName}`
 
   if ( fs.existsSync( buildWorkspace ) ) {
@@ -206,28 +203,23 @@ const buildContainerImage = async ( repoDescr ) => {
   //   5. drop a copy of dev's npmrc to use for build process
   //   6. drop a copy of package.json and the lock into the image root
   //
-  fs.renameSync( buildDir, path.join( path.dirname( buildDir ), 'workspace' ) )
-  fs.mkdirSync( buildDir )
-  fs.renameSync( path.join( path.dirname( buildDir ), 'workspace' ), buildWorkspace )
-  fs.cpSync( './docker/Dockerfile', `${buildDir}/Dockerfile` )
-  fs.cpSync( `${buildDir}/Dockerfile`, `${buildWorkspace}/Dockerfile` )
+  fs.renameSync( './build', './workspace' )
+  fs.mkdirSync( './build' )
+  fs.renameSync( './workspace', buildWorkspace )
+  fs.cpSync( './docker/Dockerfile', './build/Dockerfile' )
+  fs.cpSync( './build/Dockerfile', `${buildWorkspace}/Dockerfile` )
 
   // bashrc won't exist if we're opting out of dockerfile generation
   if ( fs.existsSync( './docker/bashrc' ) ) {
-    fs.renameSync( './docker/bashrc', `${buildDir}/bashrc` )
+    fs.renameSync( './docker/bashrc', './build/bashrc' )
   }
 
   if ( isNodeJsProject ) {
-    
-    if ( isYarnProject ) {
-      fs.cpSync( `${process.env.HOME}/.yarnrc.yml`, `${buildDir}/.yarnrc.yml` )
-    } else {
-      fs.cpSync( './package.json', `${buildWorkspace}/package.json` )
-      fs.cpSync( `${process.env.HOME}/.npmrc`, `${buildDir}/.npmrc` )
-      fs.cpSync( './package-lock.json', `${buildWorkspace}/package-lock.json` )
-    }
+    fs.cpSync( `${process.env.HOME}/.npmrc`, './build/.npmrc' )
+    fs.cpSync( './package.json', `${buildWorkspace}/package.json` )
+    fs.cpSync( './package-lock.json', `${buildWorkspace}/package-lock.json` )
   }
-  if ( isNpmWorkspace && !isYarnProject ) {
+  if ( isNpmWorkspace ) {
     fs.rm( './package-lock.json', ( err ) => {} ) // no leaf node locks in workspaces
   }
 
@@ -239,7 +231,7 @@ const buildContainerImage = async ( repoDescr ) => {
   const gcloudProjectNumber = await shellCmd( `gcloud projects describe ${artifactProject} --format="value(projectNumber)"` )
   
   // build the cloudbuild.yaml from the handlebars template
-  const cloudBuildFile = `${buildDir}/cloudbuild.yaml`
+  const cloudBuildFile = './build/cloudbuild.yaml'
   let cloudBuildSteps
   let imagePlatformString
   if ( isPythonProject || ( imagePlatform.length === 1 && imagePlatform[0] === 'linux/arm64' ) || imagePlatform.length > 1 ) {
@@ -269,12 +261,12 @@ const buildContainerImage = async ( repoDescr ) => {
   ` ) )
 
   if ( process.env.DRY_RUN === '1' ) {
-    log( `Would have run => ${cloudBuildCmd} ${cloudBuildLogs} ${cloudBuildCfg} ${buildDir}` )
+    log( `Would have run => ${cloudBuildCmd} ${cloudBuildLogs} ${cloudBuildCfg} ./build` )
     log( '\n***Exiting from DRY_RUN\n' )
     process.exit( 0 )
   }
 
-  await shellCmd( `${cloudBuildCmd} ${cloudBuildLogs} ${cloudBuildCfg} ${buildDir}`, { stdio : 'inherit' } )
+  await shellCmd( `${cloudBuildCmd} ${cloudBuildLogs} ${cloudBuildCfg} ./build`, { stdio : 'inherit' } )
 }
 
 const repoCleanup = async () => {

package/src/Utils.mjs

@@ -104,7 +104,7 @@ export const establishOauthAccess = async ( registryLocation = 'us-docker.pkg.de
   //
   // Get the current access token and use it to login to the registry with helm.
   try {
-    const accessToken = await shellCmd( 'gcloud auth print-access-token' )
+    const accessToken = ( await shellCmd( 'gcloud auth print-access-token' ) ).trim()
     // -p is frowned upon but using a pipe | is problematic with shellCmd (execa)
     const registryLoginCommand = `helm registry login -u oauth2accesstoken -p ${accessToken}`
 
@@ -224,6 +224,15 @@ export const gitRepoIsDirty = async () => {
   return cleanliness?.length > 0
 }
 
+export const parseYamlFile = async ( filePath ) => {
+  try {
+    const fileContent = await fs.promises.readFile( filePath, 'utf8' )
+    return YAML.load( fileContent )
+  } catch ( error ) {
+    throw new Error( `Failed to parse YAML file ${filePath}: ${error.message}` )
+  }
+}
+
 export const parseJsonFile = async ( jsonFile ) => {
   // TODO: rework this file exists logic / throw
   if ( !fs.existsSync( jsonFile ) ) { return undefined } // eslint-disable-line security/detect-non-literal-fs-filename
@@ -525,11 +534,10 @@ export const getRepositoryDescr = async () => {
   const gitRoot = await getGitRootDirectory()
   const gitHooksPath = await getGitHooksPath()
   const { branch : gitBranch, upstream : gitUpstream } = await getGitBranchAndUpstream()
-  const subPkgs = await glob( `${gitRoot}/**/**/package.json`, { ignore : '/**/node_modules/**' } )
+  const subPkgs = await glob( `${gitRoot}/packages/**/package.json`, { ignore : '/**/node_modules/**' } )
   const helmChart = await parseHelmChart()
   const rootPackageJson = await parseJsonFile( `${gitRoot}/package.json` )
   const rootPyProjectToml = await parsePyProjectToml( `${gitRoot}/pyproject.toml` )
-  const isYarnProject = fs.existsSync( path.join( gitRoot, 'yarn.lock' ) ) || fs.existsSync( path.join( gitRoot, '.yarn' ) )
 
   return {
     currentDir : process.cwd(),
@@ -547,7 +555,6 @@ export const getRepositoryDescr = async () => {
     rootPackageJson,
     rootPyProjectToml,
     subPkgs,
-    isYarnProject
   }
 }
 
@@ -562,7 +569,6 @@ export const analyzeRepository = async ( giveGuidance ) => {
     rootPackageJson,
     rootPyProjectToml,
     isNpmWorkspace,
-    isYarnProject
   } = await getRepositoryDescr()
 
   if ( isMonoRepo && rootPackageJson.isInvalid ) {
@@ -671,6 +677,5 @@ export const analyzeRepository = async ( giveGuidance ) => {
     packageVersion,
     subPkgs,
     wsName,
-    isYarnProject
   }
 }

package/src/artifacts/ArtifactPuller.mjs

@@ -0,0 +1,177 @@
+/* eslint-disable security/detect-non-literal-fs-filename */
+import fs from 'node:fs'
+
+import { shellCmd, log, debug, err } from '../Utils.mjs'
+
+import { toExplicitPath, deduplicatePath, convertGenericArtifactNameToPath } from './Utils.mjs'
+
+class ArtifactPuller {
+  constructor( artifact ) {
+    this.artifact = artifact
+  }
+
+  async pull() {
+    throw new Error( 'Not implemented' )
+  }
+}
+
+class GenericArtifactPuller extends ArtifactPuller {
+
+  async prepareFileDownload( tmpFilePath, finalFilePath ) {
+    // Ensure directories exist
+    fs.mkdirSync( tmpFilePath.split( '/' ).slice( 0, -1 ).join( '/' ), { recursive : true } )
+    fs.mkdirSync( finalFilePath.split( '/' ).slice( 0, -1 ).join( '/' ), { recursive : true } )
+
+    // Ensure no conflicting files exist
+    if ( fs.existsSync( tmpFilePath ) ) {
+      fs.unlinkSync( tmpFilePath )
+    }
+    if ( fs.existsSync( finalFilePath ) ) {
+      fs.unlinkSync( finalFilePath )
+    }
+  }
+
+  async cleanupFileDownload( tmpFilePath, finalFilePath ) {
+    // Delete the tmp file
+    if ( fs.existsSync( tmpFilePath ) ) {
+      fs.unlinkSync( tmpFilePath )
+    }
+    // Delete the tmp directory
+    if ( fs.existsSync( tmpFilePath.split( '/' ).slice( 0, -1 ).join( '/' ) ) ) {
+      fs.rmSync( tmpFilePath.split( '/' ).slice( 0, -1 ).join( '/' ), { recursive : true } )
+    }
+  }
+
+  async downloadFile( remoteFilePath, localFilePath ) {
+    debug( { remoteFilePath, localFilePath }, '<==Download File' )
+
+    // 1 dir per file to avoid dir creation and deletion race conditions for files in the same directory
+    const tmpDirectoryPath = `/tmp/${remoteFilePath.replaceAll( '/', '_' ).replaceAll( '.', '_' )}`
+    const tmpFilePath = `${tmpDirectoryPath}/${remoteFilePath.split( '/' ).pop()}`
+
+    await this.prepareFileDownload( tmpFilePath, localFilePath )
+
+    try {
+      const command = `gcloud artifacts generic download \
+      --project=${this.artifact.gcp_project_id} \
+      --location=${this.artifact.gcp_location} \
+      --repository=${this.artifact.gcp_artifact_registry_repository_name} \
+      --package=${this.artifact.gcp_artifact_registry_package_name} \
+      --version=${this.artifact.gcp_artifact_registry_package_version} \
+      --name="${remoteFilePath}" \
+      --destination=${tmpDirectoryPath}`
+
+      debug( { command }, '<==Download File Command' )
+
+      await shellCmd( command )
+
+      // Check if file exists in the tmp path
+      if ( !fs.existsSync( tmpFilePath ) ) {
+        debug( { tmpFilePath }, '<==File does not exist in the tmp path' )
+        return false
+      }
+
+      debug( { tmpFilePath, localFilePath }, '<==Copying file' )
+
+      await fs.copyFileSync( tmpFilePath, localFilePath )
+
+      // Check if file exists in the local path
+      if ( !fs.existsSync( localFilePath ) ) {
+        debug( { localFilePath }, '<==File does not exist in the local path' )
+        return false
+      }
+
+      return true
+    } catch ( error ) {
+      err( `Error downloading file: ${remoteFilePath} ${error.message}` )
+      return false
+    } finally {
+      await this.cleanupFileDownload( tmpFilePath, localFilePath )
+    }
+  }
+
+  async downloadDirectory( localPath ) {
+    const command = `gcloud artifacts generic download \
+      --project=${this.artifact.gcp_project_id} \
+      --location=${this.artifact.gcp_location} \
+      --repository=${this.artifact.gcp_artifact_registry_repository_name} \
+      --package=${this.artifact.gcp_artifact_registry_package_name} \
+      --version=${this.artifact.gcp_artifact_registry_package_version} \
+      --destination=${localPath}`
+
+    debug( { command }, '<==Download Directory Command' )
+
+    await shellCmd( command )
+  }
+
+  async downloadNestedDirectory( remotePath, localPath ) {
+    debug( { remotePath, localPath }, '<==Download Nested Directory' )
+
+    const files = await this.listFiles( remotePath )
+    await Promise.all(
+      files
+        .filter( file => convertGenericArtifactNameToPath( file.name ).startsWith( remotePath ) )
+        .map( async ( file ) => {
+          const remoteFilePath = convertGenericArtifactNameToPath( file.name )
+          const localFilePath = deduplicatePath( `${localPath}/${remoteFilePath.replaceAll( remotePath, '' )}` )
+          await this.downloadFile( remoteFilePath, localFilePath )
+        } )
+    )
+  }
+
+  async listFiles( ) {
+    const command = `gcloud artifacts files list \
+        --project=${this.artifact.gcp_project_id} \
+        --location=${this.artifact.gcp_location} \
+        --repository=${this.artifact.gcp_artifact_registry_repository_name} \
+        --package=${this.artifact.gcp_artifact_registry_package_name} \
+        --version ${this.artifact.gcp_artifact_registry_package_version} \
+        --format="json"`
+
+    debug( { command }, '<==List Files Command' )
+      
+    const result = await shellCmd( command )
+  
+    // Parse the JSON response
+    const files = JSON.parse( result )
+    return files
+  }
+
+  async pull() {
+    log( `Pulling artifact: ${this.artifact.name}` )
+    
+    debug( { artifact : this.artifact }, '<==Pulling artifact' )
+
+    try {
+      if ( this.artifact.remote_file_path && this.artifact.local_file_path ) {
+        await this.downloadFile( this.artifact.remote_file_path, toExplicitPath( this.artifact.local_file_path ) )
+      } else if ( this.artifact.remote_file_path && this.artifact.local_path ) {
+        await this.downloadFile( this.artifact.remote_file_path, toExplicitPath( `${this.artifact.local_path}/${this.artifact.remote_file_path.split( '/' ).pop()}` ) )
+      } else if ( this.artifact.remote_path && this.artifact.local_path ) {
+        await this.downloadNestedDirectory( this.artifact.remote_path, toExplicitPath( this.artifact.local_path ) )
+      } else if ( this.artifact.remote_path && !this.artifact.local_path && !this.artifact.local_file_path ) {
+        await this.downloadDirectory( this.artifact.remote_path, '.' )
+      } else if ( !this.artifact.remote_path && !this.artifact.remote_file_path && this.artifact.local_path ) {
+        await this.downloadDirectory( toExplicitPath( this.artifact.local_path ) )
+      } else {
+        throw new Error( 'No valid paths provided' )
+      }
+
+      log( `Successfully pulled artifact: ${this.artifact.name}` )
+
+      return true
+      
+      // if ( !this.artifact.remote_path && !this.artifact.remote_file_path && this.local_file_path ) {
+      //   throw new Error( '' )
+      // }
+      // if ( this.artifact.remote_path && this.artifact.local_file_path ) {
+      //   throw new Error( '' )
+      // }
+    } catch ( error ) {
+      err( `Error pulling artifact: ${this.artifact.name} ${error.message}` )
+    }
+    return false
+  }
+}
+
+export { ArtifactPuller, GenericArtifactPuller }

package/src/artifacts/ArtifactPusher.mjs

@@ -0,0 +1,86 @@
+/* eslint-disable security/detect-non-literal-fs-filename */
+import { shellCmd, log, err, debug } from '../Utils.mjs'
+
+import { convertGenericArtifactNameToPath } from './Utils.mjs'
+
+class ArtifactPusher {
+  constructor( artifact ) {
+    this.artifact = artifact
+  }
+
+  async push() {
+    throw new Error( 'Not implemented' )
+  }
+}
+
+class GenericArtifactPusher extends ArtifactPusher {
+
+  async listFiles( ) {
+    const command = `gcloud artifacts files list \
+        --project=${this.artifact.gcp_project_id} \
+        --location=${this.artifact.gcp_location} \
+        --repository=${this.artifact.gcp_artifact_registry_repository_name} \
+        --package=${this.artifact.gcp_artifact_registry_package_name} \
+        --version ${this.artifact.gcp_artifact_registry_package_version} \
+        --format="json"`
+
+    debug( { command }, '<==List Files Command' )
+      
+    const result = await shellCmd( command )
+  
+    // Parse the JSON response
+    const files = JSON.parse( result )
+
+    return files
+  }
+    
+  async push() {
+    log( `Pushing artifact: ${this.artifact.name}` )
+
+    if ( this.artifact.remote_file_path ) {
+      err( 'Remote file path is not supported for pushing artifacts' )
+      return false
+    }
+
+    try {
+   
+      let command = ''
+
+      command = `gcloud artifacts generic upload \
+      --project=${this.artifact.gcp_project_id} \
+      --location=${this.artifact.gcp_location} \
+      --repository=${this.artifact.gcp_artifact_registry_repository_name} \
+      --package=${this.artifact.gcp_artifact_registry_package_name} \
+      --version=${this.artifact.gcp_artifact_registry_package_version}`
+
+      if ( this.artifact.local_path ) {
+        command += ` --source-directory=${this.artifact.local_path}`
+        command += ' --skip-existing'
+      } else if ( this.artifact.local_file_path ) {
+        const files = await this.listFiles( this.artifact.remote_path )
+        if ( files.some( file => convertGenericArtifactNameToPath( file.name ) === `${this.artifact.remote_path}/${this.artifact.remote_file_path.split( '/' ).pop()}` ) ) {
+          err( `File already exists in the artifact registry: ${this.artifact.local_file_path}` )
+          return false
+        }
+        command += ` --source=${this.artifact.local_file_path}`
+      }
+
+      if ( this.artifact.remote_path ) {
+        command += ` --destination-path=${this.artifact.remote_path}`
+      }
+
+      debug( { command }, '<==Upload Command' )
+        
+      await shellCmd( command )
+      
+      log( `Successfully pushed artifact: ${this.artifact.name}` )
+
+      return true
+    } catch ( error ) {
+      err( `Error pushing artifact: ${this.artifact.name} ${error.message}` )
+      return false
+    }
+  }
+}
+
+export { ArtifactPusher, GenericArtifactPusher }

package/src/artifacts/Structs.mjs

@@ -0,0 +1,91 @@
+import { assign, object, string, array, optional, enums, union, refine } from 'superstruct'
+
+const ArtifactTypeEnum = {
+  GENERIC : 'generic',
+}
+
+// Superstruct schema for individual artifact configuration
+const PartialArtifactSchema = object( {
+  name : string(),
+  type : optional( enums( Object.values( ArtifactTypeEnum ) ) ),
+  gcp_project_id : optional( string() ),
+  gcp_location : optional( string() ),
+  gcp_artifact_registry_repository_name : optional( string() ),
+  gcp_artifact_registry_package_name : optional( string() ),
+  gcp_artifact_registry_package_version : optional( string() )
+} )
+
+const ArtifactSchema = assign( PartialArtifactSchema, object( {
+  name : string(),
+  type : enums( Object.values( ArtifactTypeEnum ) ),
+  gcp_project_id : string(),
+  gcp_location : string(),
+  gcp_artifact_registry_repository_name : string(),
+  gcp_artifact_registry_package_name : string(),
+  gcp_artifact_registry_package_version : string()
+} ) )
+
+const PartialGenericArtifactSchema = refine(
+  assign( PartialArtifactSchema, object( {
+    type : enums( [ ArtifactTypeEnum.GENERIC ] ),
+    local_file_path : optional( string() ),
+    local_path : optional( string() ),
+    remote_file_path : optional( string() ),
+    remote_path : optional( string() )
+  } ) ),
+  'ConflictingPaths',
+  ( value ) => {
+    if ( value.local_file_path && value.local_path ) {
+      return 'Only one of local_file_path or local_path must be provided'
+    }
+    if ( value.remote_file_path && value.remote_path ) {
+      return 'Only one of remote_file_path or remote_path must be provided'
+    }
+    return true
+  }
+)
+
+const GenericArtifactSchema = refine(
+  assign( ArtifactSchema, object( {
+    local_file_path : optional( string() ),
+    local_path : optional( string() ),
+    remote_file_path : optional( string() ),
+    remote_path : optional( string() )
+  } ) ),
+  'ConflictingPaths',
+  ( value ) => {
+    if ( value.local_file_path && value.local_path ) {
+      return 'Only one of local_file_path or local_path must be provided'
+    }
+    if ( value.remote_file_path && value.remote_path ) {
+      return 'Only one of remote_file_path or remote_path must be provided'
+    }
+    return true
+  }
+)
+
+// Superstruct schema for defaults configuration
+const DefaultsSchema = object( {
+  gcp_project_id : optional( string() ),
+  gcp_location : optional( string() ),
+  gcp_artifact_registry_repository_name : optional( string() ),
+  gcp_artifact_registry_package_name : optional( string() ),
+  gcp_artifact_registry_package_version : optional( string() )
+} )
+
+// Superstruct schema for the complete artifacts configuration with defaults
+const ArtifactsSchema = object( {
+  defaults : optional( DefaultsSchema ),
+  artifacts : array( union( [ PartialArtifactSchema, PartialGenericArtifactSchema ] ) )
+} )
+
+const FlattenedArtifactsSchema = array( assign( union( [ ArtifactSchema, GenericArtifactSchema ] ) ) )
+
+export {
+  ArtifactTypeEnum,
+  ArtifactsSchema,
+  FlattenedArtifactsSchema,
+  ArtifactSchema,
+  DefaultsSchema,
+  GenericArtifactSchema,
+}

package/src/artifacts/Utils.mjs

@@ -0,0 +1,92 @@
+import fs from 'node:fs'
+import crypto from 'crypto'
+
+import { validate } from 'superstruct'
+
+import { parseYamlFile, warning } from '../Utils.mjs'
+
+import { ArtifactTypeEnum, ArtifactsSchema, GenericArtifactSchema } from './Structs.mjs'
+
+const getArtifactsSchema = async ( artifactsFilePath = './artifacts.yml' ) => {
+  const artifactsConfig = await parseYamlFile( artifactsFilePath )
+  const [ error, result ] = validate( artifactsConfig, ArtifactsSchema )
+  if ( error ) {
+    throw new Error( `Invalid artifacts.yml file: ${error.message}` )
+  }
+  return result
+}
+
+const flattenArtifactsSchema = ( artifactsSchema ) => {
+  return artifactsSchema.artifacts.reduce( ( flattenedArtifacts, artifact ) => {
+    const mergedArtifact = {
+      ...artifactsSchema.defaults,
+      ...artifact
+    }
+    
+    let schema
+    switch ( mergedArtifact.type ) {
+      case ArtifactTypeEnum.GENERIC:
+        schema = GenericArtifactSchema
+        break
+      default:
+        warning( `Unsupported artifact type "${mergedArtifact.type}"` )
+        break
+    }
+
+    if ( !schema ) {
+      warning( `Invalid artifact type "${mergedArtifact.type}"` )
+      return flattenedArtifacts
+    }
+    
+    const [ error, validatedArtifact ] = validate( mergedArtifact, schema )
+    
+    if ( error ) {
+      warning( `Invalid artifact "${mergedArtifact.name}": ${error.message}` )
+      return flattenedArtifacts
+    }
+    
+    return [ ...flattenedArtifacts, validatedArtifact ]
+  }, [] )
+}
+
+const toImplicitPath = ( path ) => {
+  let implicitPath = path
+  // Remove leading './' if present
+  if ( implicitPath.startsWith( './' ) ) {
+    implicitPath = implicitPath.slice( 2 )
+  }
+  // Remove trailing slash
+  implicitPath = implicitPath.replace( /\/+$/, '' )
+  return implicitPath
+}
+
+const toExplicitPath = ( path ) => {
+  let explicitPath = path
+  // Keep absolute paths and paths already starting with '.' as-is
+  if ( !path.startsWith( '/' ) && !path.startsWith( '.' ) ) {
+    // Add './' to relative paths
+    explicitPath = `./${explicitPath}`
+  }
+  return explicitPath
+}
+
+const deduplicatePath = ( path ) => {
+  return path.replaceAll( '//', '/' )
+}
+
+const convertGenericArtifactNameToPath = ( genericArtifactName ) => {
+  return genericArtifactName.split( ':' ).pop().replaceAll( '%2F', '/' ).replaceAll( '%3A', ':' )
+}
+
+const calculateHash = ( path ) => {
+  try {
+    const hash = crypto.createHash( 'sha256' )
+    hash.update( fs.readFileSync( path ) )
+    return hash.digest( 'base64url' )
+  } catch ( error ) {
+    console.error( error )
+    throw new Error( `Failed to calculate hash for artifact ${path}: ${error.message}` )
+  }
+}
+
+export { calculateHash, getArtifactsSchema, flattenArtifactsSchema, toImplicitPath, toExplicitPath, deduplicatePath, convertGenericArtifactNameToPath }