or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

caching.md discovery.md download.md extraction.md index.md manifest.md versions.md

tile.json

Manifest System

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

Capabilities

Get Manifest from Repository

Retrieves a tool manifest from a GitHub repository containing tool release information.

/**
 * Retrieves a tool manifest from a GitHub repository
 * @param owner - GitHub repository owner
 * @param repo - GitHub repository name
 * @param auth - Optional GitHub authentication token
 * @param branch - Optional branch name (defaults to 'master')
 * @returns Promise resolving to array of tool releases
 */
function getManifestFromRepo(
  owner: string,
  repo: string,
  auth?: string,
  branch?: string
): Promise<IToolRelease[]>;

Usage Examples:

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

// Get manifest from public repository
const manifest = await getManifestFromRepo("actions", "python-versions");

// Get manifest with authentication
const manifest = await getManifestFromRepo(
  "my-org",
  "tool-versions",
  "ghp_your_token_here"
);

// Get manifest from specific branch
const manifest = await getManifestFromRepo(
  "actions",
  "node-versions",
  undefined,
  "v2"
);

Find from Manifest

Finds a tool release from a manifest that matches the specified version and architecture criteria.

/**
 * Finds a tool release from a manifest that matches version and architecture
 * @param versionSpec - Version specification (exact version or semantic range)
 * @param stable - Whether to only consider stable releases
 * @param manifest - Array of tool releases to search
 * @param archFilter - Optional architecture filter (defaults to os.arch())
 * @returns Promise resolving to matching tool release or undefined
 */
function findFromManifest(
  versionSpec: string,
  stable: boolean,
  manifest: IToolRelease[],
  archFilter?: string
): Promise<IToolRelease | undefined>;

Usage Examples:

import { getManifestFromRepo, findFromManifest } from "@actions/tool-cache";

// Get manifest and find specific version
const manifest = await getManifestFromRepo("actions", "python-versions");
const release = await findFromManifest("3.11.x", true, manifest);

if (release) {
  console.log(`Found Python ${release.version}`);
  console.log(`Download URL: ${release.files[0].download_url}`);
}

// Find with specific architecture
const x64Release = await findFromManifest(
  ">=3.10.0",
  true,
  manifest,
  "x64"
);

// Find including pre-release versions
const anyRelease = await findFromManifest("3.12.x", false, manifest);

Manifest Data Types

Tool Release Interface

Represents a complete tool release with metadata and downloadable files.

interface IToolRelease {
  /** Version of the tool (semantic version) */
  version: string;
  /** Whether this is a stable release */
  stable: boolean;
  /** URL to the release page or announcement */
  release_url: string;
  /** Array of downloadable files for different platforms */
  files: IToolReleaseFile[];
}

Tool Release File Interface

Represents a downloadable file for a specific platform and architecture.

interface IToolReleaseFile {
  /** Filename of the downloadable file */
  filename: string;
  /** Target platform (e.g., 'linux', 'darwin', 'win32') */
  platform: string;
  /** Optional platform version filter (semantic version or range) */
  platform_version?: string;
  /** Target architecture (e.g., 'x64', 'arm64', 'x86') */
  arch: string;
  /** Direct download URL for the file */
  download_url: string;
}

Complete Manifest Workflow

Download Tool from Manifest

import {
  getManifestFromRepo,
  findFromManifest,
  downloadTool,
  extractTar,
  cacheDir
} from "@actions/tool-cache";
import * as core from "@actions/core";

async function setupToolFromManifest(
  owner: string,
  repo: string,
  toolName: string,
  versionSpec: string
): Promise<string> {
  // Get the manifest
  const manifest = await getManifestFromRepo(owner, repo);
  
  // Find matching release
  const release = await findFromManifest(versionSpec, true, manifest);
  
  if (!release) {
    throw new Error(`No matching release found for ${toolName} ${versionSpec}`);
  }
  
  // Get the appropriate file for current platform
  const file = release.files[0]; // findFromManifest returns filtered files
  
  core.info(`Downloading ${toolName} ${release.version} from ${file.download_url}`);
  
  // Download and extract
  const downloadPath = await downloadTool(file.download_url);
  const extractedPath = await extractTar(downloadPath);
  
  // Cache the tool
  const cachedPath = await cacheDir(extractedPath, toolName, release.version);
  
  return cachedPath;
}

Multi-Platform Tool Setup

import { getManifestFromRepo, findFromManifest } from "@actions/tool-cache";
import * as os from "os";

async function getToolForAllPlatforms(toolName: string, version: string) {
  const manifest = await getManifestFromRepo("actions", `${toolName}-versions`);
  const platforms = ["linux", "darwin", "win32"];
  const architectures = ["x64", "arm64"];
  
  const results: Array<{platform: string, arch: string, release: IToolRelease | undefined}> = [];
  
  for (const platform of platforms) {
    for (const arch of architectures) {
      // Note: This is a conceptual example - findFromManifest doesn't take platform parameter
      // You would need to filter the manifest manually or extend the function
      const release = await findFromManifest(version, true, manifest, arch);
      
      if (release) {
        const platformFile = release.files.find(f => 
          f.platform === platform && f.arch === arch
        );
        
        if (platformFile) {
          results.push({ platform, arch, release });
        }
      }
    }
  }
  
  return results;
}

Manifest File Format

Example Manifest Structure

[
  {
    "version": "3.11.5",
    "stable": true,
    "release_url": "https://github.com/python/cpython/releases/tag/v3.11.5",
    "files": [
      {
        "filename": "python-3.11.5-linux-x64.tar.gz",
        "platform": "linux",
        "arch": "x64",
        "download_url": "https://github.com/actions/python-versions/releases/download/3.11.5-1234567890/python-3.11.5-linux-x64.tar.gz"
      },
      {
        "filename": "python-3.11.5-darwin-x64.tar.gz",
        "platform": "darwin",
        "arch": "x64",
        "download_url": "https://github.com/actions/python-versions/releases/download/3.11.5-1234567890/python-3.11.5-darwin-x64.tar.gz"
      },
      {
        "filename": "python-3.11.5-win32-x64.zip",
        "platform": "win32",
        "arch": "x64",
        "download_url": "https://github.com/actions/python-versions/releases/download/3.11.5-1234567890/python-3.11.5-win32-x64.zip"
      }
    ]
  },
  {
    "version": "3.12.0b4",
    "stable": false,
    "release_url": "https://github.com/python/cpython/releases/tag/v3.12.0b4",
    "files": [
      {
        "filename": "python-3.12.0b4-linux-x64.tar.gz",
        "platform": "linux",
        "platform_version": ">=18.04",
        "arch": "x64",
        "download_url": "https://github.com/actions/python-versions/releases/download/3.12.0b4-987654321/python-3.12.0b4-linux-x64.tar.gz"
      }
    ]
  }
]

Implementation Details

Platform Matching

Automatic detection: Uses os.platform() to determine current platform
Platform names: Standard Node.js platform identifiers ('linux', 'darwin', 'win32', etc.)
Version filtering: Optional platform_version supports semantic version ranges
OS version resolution: Automatically detects and matches OS versions on macOS and Linux

Architecture Filtering

Default architecture: Uses current platform architecture if not specified
Supported architectures: Standard Node.js architecture identifiers
Cross-compilation: Can find releases for different target architectures

Version Resolution

Semantic versioning: Full semver range support for version specifications
Stability filtering: stable parameter filters out pre-release versions when true
Sorting: Manifests should be sorted by version (descending) for optimal performance

Authentication

GitHub tokens: Pass personal access tokens or GitHub Actions tokens
Rate limiting: Authentication helps avoid GitHub API rate limits
Private repositories: Required for accessing private repository manifests

Error Handling

import { getManifestFromRepo, findFromManifest } from "@actions/tool-cache";

try {
  const manifest = await getManifestFromRepo("owner", "repo");
  const release = await findFromManifest("1.0.0", true, manifest);
  
  if (!release) {
    console.log("No matching release found");
  }
} catch (error) {
  if (error.message.includes("404")) {
    console.log("Repository or manifest not found");
  } else if (error.message.includes("rate limit")) {
    console.log("GitHub API rate limit exceeded - try with authentication");
  } else {
    console.log(`Manifest error: ${error.message}`);
  }
}