Tool Discovery

/**
 * Finds the path to a tool in the local installed tool cache
 * @param toolName - Name of the tool to find
 * @param versionSpec - Version specification (exact version or semantic range)
 * @param arch - Optional architecture filter (defaults to current platform architecture)
 * @returns Path to the tool directory, or empty string if not found
 */
function find(
  toolName: string,
  versionSpec: string,
  arch?: string
): string;

import { find } from "@actions/tool-cache";
import * as core from "@actions/core";

// Find exact version
const nodePath = find("node", "18.17.0");
if (nodePath) {
  core.addPath(nodePath);
}

// Find with semantic version range
const pythonPath = find("python", "3.x");
if (pythonPath) {
  core.addPath(pythonPath);
}

// Find with more specific range
const toolPath = find("my-tool", ">=2.0.0 <3.0.0");

// Find with specific architecture
const toolPath = find("node", "16.x", "x64");

// Check if tool exists before using
const javaPath = find("java", "11");
if (!javaPath) {
  throw new Error("Java 11 not found in tool cache");
}

/**
 * Finds all versions of a tool that are installed in the local tool cache
 * @param toolName - Name of the tool to search for
 * @param arch - Optional architecture filter (defaults to all architectures)
 * @returns Array of version strings sorted in descending order
 */
function findAllVersions(toolName: string, arch?: string): string[];

import { findAllVersions } from "@actions/tool-cache";

// Get all cached versions of a tool
const nodeVersions = findAllVersions("node");
console.log("Available Node.js versions:", nodeVersions);
// Example output: ["18.17.0", "16.20.1", "14.21.3"]

// Get versions for specific architecture
const x64Versions = findAllVersions("python", "x64");

// Check if any version is available
const versions = findAllVersions("my-tool");
if (versions.length === 0) {
  console.log("No cached versions of my-tool found");
}

// Find latest cached version
const latestVersion = findAllVersions("java")[0]; // Array is sorted descending

find("node", "18.17.0");        // Exact match
find("python", "3.11.2");       // Exact match
find("java", "11.0.19");        // Exact match

find("node", "18.x");           // Latest 18.x version
find("python", "3.x");          // Latest 3.x version
find("tool", ">=2.0.0");        // Version 2.0.0 or higher
find("tool", "~1.2.0");         // Compatible with 1.2.0
find("tool", "^2.1.0");         // Compatible with 2.1.0
find("tool", ">=1.0.0 <2.0.0"); // Range between 1.0.0 and 2.0.0

find("node", "18.x", "x64");    // 64-bit version
find("node", "18.x", "arm64");  // ARM64 version
find("python", "3.x", "x86");   // 32-bit version

import { find, findAllVersions } from "@actions/tool-cache";
import * as core from "@actions/core";

function checkToolAvailability(toolName: string, versionSpec: string): boolean {
  const toolPath = find(toolName, versionSpec);
  if (toolPath) {
    core.info(`Found ${toolName} ${versionSpec} at ${toolPath}`);
    return true;
  }
  
  const availableVersions = findAllVersions(toolName);
  if (availableVersions.length > 0) {
    core.warning(`${toolName} ${versionSpec} not found. Available versions: ${availableVersions.join(", ")}`);
  } else {
    core.warning(`No cached versions of ${toolName} found`);
  }
  
  return false;
}

import { find, findAllVersions } from "@actions/tool-cache";
import * as core from "@actions/core";

async function setupMultipleNodeVersions() {
  const versions = ["16.x", "18.x", "20.x"];
  const foundVersions: string[] = [];
  
  for (const version of versions) {
    const nodePath = find("node", version);
    if (nodePath) {
      foundVersions.push(version);
      // Add to PATH or set up environment
      core.addPath(nodePath);
    }
  }
  
  core.info(`Set up Node.js versions: ${foundVersions.join(", ")}`);
  
  // List all available Node versions
  const allVersions = findAllVersions("node");
  core.debug(`All cached Node versions: ${allVersions.join(", ")}`);
}

import { find } from "@actions/tool-cache";

function findToolWithFallback(toolName: string, preferredVersions: string[]): string {
  for (const version of preferredVersions) {
    const toolPath = find(toolName, version);
    if (toolPath) {
      return toolPath;
    }
  }
  
  throw new Error(`None of the preferred versions found for ${toolName}: ${preferredVersions.join(", ")}`);
}

// Usage
const pythonPath = findToolWithFallback("python", ["3.11.x", "3.10.x", "3.9.x", "3.x"]);

// find() returns empty string when not found
const toolPath = find("nonexistent-tool", "1.0.0");
if (toolPath === "") {
  console.log("Tool not found");
}

// findAllVersions() returns empty array when not found
const versions = findAllVersions("nonexistent-tool");
if (versions.length === 0) {
  console.log("No versions found");
}