tessl/npm-actions--tool-cache

Functions necessary for downloading and caching tools in GitHub Actions workflows

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Actions Tool Cache

Name: tessl/npm-actions--tool-cache
Author: tessl

Actions Tool Cache is a comprehensive TypeScript library that provides essential functionality for downloading, extracting, caching, and retrieving tools within GitHub Actions workflows. It offers cross-platform support for downloading files from URLs with authentication, platform-specific extraction capabilities for various archive formats, intelligent caching system for storing tools locally, and efficient tool discovery through semantic version matching.

Package Information

Package Name: @actions/tool-cache
Package Type: npm
Language: TypeScript
Installation: npm install @actions/tool-cache

Core Imports

import {
  downloadTool,
  extractZip,
  extractTar,
  extract7z,
  extractXar,
  cacheDir,
  cacheFile,
  find,
  findAllVersions
} from "@actions/tool-cache";

For CommonJS:

const {
  downloadTool,
  extractZip,
  extractTar,
  extract7z,
  extractXar,
  cacheDir,
  cacheFile,
  find,
  findAllVersions
} = require("@actions/tool-cache");

Basic Usage

import * as tc from "@actions/tool-cache";
import * as core from "@actions/core";

// Download, extract, cache, and use a tool
async function setupNode() {
  // Download tool
  const downloadPath = await tc.downloadTool(
    "https://nodejs.org/dist/v18.17.0/node-v18.17.0-linux-x64.tar.gz"
  );
  
  // Extract archive
  const extractedPath = await tc.extractTar(downloadPath);
  
  // Cache the tool
  const cachedPath = await tc.cacheDir(extractedPath, "node", "18.17.0");
  
  // Add to PATH
  core.addPath(cachedPath);
}

// Find previously cached tool
const nodePath = tc.find("node", "18.x");
if (nodePath) {
  core.addPath(nodePath);
}

Architecture

Actions Tool Cache is built around several key components:

Download System: HTTP client with retry logic, authentication support, and robust error handling for reliable tool acquisition
Extraction Engines: Platform-specific extraction support for ZIP, tar (with compression), 7z, and XAR archive formats
Caching Layer: Persistent tool storage with semantic versioning, architecture awareness, and efficient lookup mechanisms
Discovery Engine: Semantic version matching with range support for finding cached tools and versions
Manifest System: GitHub repository-based tool manifest support for automated tool discovery and selection

Capabilities

Tool Download

HTTP-based tool downloading with authentication, retry logic, and error handling. Supports custom headers and destinations.

function downloadTool(
  url: string,
  dest?: string,
  auth?: string,
  headers?: OutgoingHttpHeaders
): Promise<string>;

class HTTPError extends Error {
  constructor(readonly httpStatusCode: number | undefined);
}

Download Tools

Archive Extraction

Archive extraction supporting multiple formats including ZIP, tar with various compression schemes, 7z (Windows only), and XAR (macOS).

function extractZip(file: string, dest?: string): Promise<string>;
function extractTar(
  file: string,
  dest?: string,
  flags?: string | string[]
): Promise<string>;
function extract7z(
  file: string,
  dest?: string,
  _7zPath?: string
): Promise<string>;
function extractXar(
  file: string,
  dest?: string,
  flags?: string | string[]
): Promise<string>;

Archive Extraction

Tool Caching

Persistent tool storage system with semantic versioning and architecture support for efficient tool management across workflow runs.

function cacheDir(
  sourceDir: string,
  tool: string,
  version: string,
  arch?: string
): Promise<string>;
function cacheFile(
  sourceFile: string,
  targetFile: string,
  tool: string,
  version: string,
  arch?: string
): Promise<string>;

Tool Caching

Tool Discovery

Semantic version-aware tool discovery for finding cached tools with support for version ranges and architecture filtering.

function find(
  toolName: string,
  versionSpec: string,
  arch?: string
): string;
function findAllVersions(toolName: string, arch?: string): string[];

Tool Discovery

Manifest-Based Resolution

GitHub repository-based tool manifest system for automated tool discovery, version resolution, and platform-specific downloads.

function getManifestFromRepo(
  owner: string,
  repo: string,
  auth?: string,
  branch?: string
): Promise<IToolRelease[]>;
function findFromManifest(
  versionSpec: string,
  stable: boolean,
  manifest: IToolRelease[],
  archFilter?: string
): Promise<IToolRelease | undefined>;

interface IToolRelease {
  version: string;
  stable: boolean;
  release_url: string;
  files: IToolReleaseFile[];
}

interface IToolReleaseFile {
  filename: string;
  platform: string;
  platform_version?: string;
  arch: string;
  download_url: string;
}

Manifest System

Version Utilities

Semantic version evaluation and validation utilities for working with version specifications and ranges.

function isExplicitVersion(versionSpec: string): boolean;
function evaluateVersions(
  versions: string[],
  versionSpec: string
): string;

Version Utilities

Types

import { OutgoingHttpHeaders } from "http";

class HTTPError extends Error {
  constructor(readonly httpStatusCode: number | undefined);
}

interface IToolRelease {
  version: string;
  stable: boolean;
  release_url: string;
  files: IToolReleaseFile[];
}

interface IToolReleaseFile {
  filename: string;
  platform: string;
  platform_version?: string;
  arch: string;
  download_url: string;
}

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 2 months ago
Describes: pkg:npm/@actions/tool-cache@2.0.x
Publish Source: CLI
Badge