Added an utility that validates GitHub token.

.gitea/workflows/test.yml

@@ -1,5 +1,15 @@
 name: Test Action
-on: [push, workflow_dispatch]
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '.gitea/workflows/test.yml'
+      - 'action.yml'
+      - 'src/**'
+      - 'dist/**'
+      - 'package.json'
+      - 'package-lock.json'
 
 jobs:
   test:

.github/workflows/test.yml

@@ -0,0 +1,45 @@
+name: Test Action
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '.github/workflows/test.yml'
+      - 'action.yml'
+      - 'src/**'
+      - 'dist/**'
+      - 'package.json'
+      - 'package-lock.json'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Go ACME Setup
+        uses: skoszewski/setup-github-release@v1
+        with:
+          repository: 'go-acme/lego'
+
+      - name: Setup Hugo
+        uses: skoszewski/setup-github-release@v1
+        with:
+          repository: 'gohugoio/hugo'
+          file-name: '~hugo_extended_[^a-z]'
+
+      - name: Setup RClone
+        uses: skoszewski/setup-github-release@v1
+        with:
+          repository: 'rclone/rclone'
+
+      - name: Verify Installation
+        run: |
+          echo "Verifying installed tools..."
+          printf "\nGo ACME Lego:\n"
+          lego -v
+          printf "\nHugo:\n"
+          hugo version
+          printf "\nRClone:\n"
+          rclone version

.gitignore

@@ -3,4 +3,4 @@ lib/
 *.log
 *.map
 .DS_Store
-Notes.md
+.github/*.md

README.md

@@ -1,6 +1,55 @@
 # Setup GitHub Release Action
 
-This GitHub/Gitea Action downloads a tool from a GitHub release, extracts it, automatically finds the executable, and adds it to the system PATH. It supports platform-aware selection, recursive binary search, and tool caching.
+This project implements a GitHub Action (`setup-github-release`) and a CLI tool (`install-github-release`) that downloads a release asset from a specified GitHub repository, extracts it, searches for a binary within the extracted files, and prepares the runtime environment.
+
+## Installation / Setup
+
+### GitHub/Gitea Action
+
+Add the action to your workflow. Authenticate with `github.token` (default) or a custom token for Gitea/private repos.
+
+```yaml
+- name: Install Tool
+  uses: koszewscy/setup-github-release@v1
+  with:
+    repository: 'owner/repo'
+```
+
+### CLI Tool
+
+Install the CLI tool on any destination system with Node.js 24 or newer.
+
+**From Source:**
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/koszewscy/setup-github-release
+cd setup-github-release
+```
+
+2. Install dependencies and build the project:
+
+```bash
+npm install
+npm run build
+```
+
+3. Install the tool locally:
+
+```bash
+npm install -g .
+```
+
+After installation, the tool will be available as `install-github-release`. By default, it installs binaries to:
+
+- Linux/macOS (root): `/usr/local/bin`
+- Linux/macOS (user): `~/bin` (if exists) or `/usr/local/bin`
+- Windows: `%LOCALAPPDATA%\bin`
+
+```bash
+install-github-release rclone/rclone
+```
 
 ## Features
 
@@ -59,13 +108,96 @@ If you are unsure how the binary is named, use the `debug` flag to list all file
     debug: true
 ```
 
-## Inputs
+## Inputs / Options
 
-- `repository` (required): GitHub repository in `owner/repo` format.
-- `file-name` (optional): Literal name or regex pattern (if starts with `~`) to match the asset.
-- `binary-name` (optional): The name or regex pattern (if starts with `~`) of the binary to find. Defaults to the repository name.
-- `file-type` (optional, default: `archive`): Predefined keywords `archive`, `package`, or a custom regex pattern.
-- `debug` (optional, default: `false`): Set to `true` to log the contents of the unpacked asset.
-- `token` (optional): GitHub token for authentication (defaults to `${{ github.token }}` that is an equivalent of `${{ secrets.GITHUB_TOKEN }}`). Use `${{ secrets.GITEA_TOKEN }}` for Gitea, or create a personal access token.
+The following inputs are available for the GitHub Action, and as options for the CLI tool:
+
+- `repository` (required): The GitHub repository in the format `owner/repo` from which to download the release.
+- `file-name` (optional): The name or the regex pattern (prefixed with `~`) of the asset file to download from the release.
+- `binary-name` (optional): The name or regex pattern (prefixed with `~`) of the binary to search for within the downloaded asset. Defaults to the repository name.
+- `file-type` (optional, default: 'archive'): The regex pattern to identify the type of the file to be downloaded. There are two predefined keywords:
+
+    - 'archive': matches common archive file extensions like .zip, .tar.gz, .tar, .tgz, .7z.
+    - 'package': matches common package file extensions like .deb, .rpm, .pkg.
+    - or a custom regex pattern can be provided to match specific file types.
+
+- `install-path` (optional, CLI only): Custom installation directory for the CLI tool.
+- `update-cache` (optional, default: 'false', Action only): When set to 'false', the action will use the cached version of the tool if it is already available. If set to 'true', the action will check the latest release and update the cache if a newer version is found. If set to 'always', it will always download and install, updating the cache regardless.
+- `debug` (optional, default: 'false'): When set to `true`, the action will log the contents of the unpacked directory to the console.
+- `token` (optional): A GitHub token for authentication, useful for accessing private repositories or increasing rate limits.
+
+> **Important:** Default authentication will only work if the action is used within GitHub workflow. For Gitea or the CLI, you must provide a token explicitly (e.g. `GITHUB_TOKEN` environment variable).
+
+## CLI Usage
+
+The `install-github-release` tool follows the same logic as the Action.
+
+```bash
+Usage: install-github-release [options] <repository>
+
+Arguments:
+  repository                 The GitHub repository (owner/repo)
+
+Options:
+  -f, --file-name <name>     Asset file name or regex pattern (prefixed with ~)
+  -b, --binary-name <name>   Binary to search for (prefixed with ~ for regex)
+  -t, --file-type <type>     'archive', 'package', or custom regex (default: archive)
+  -p, --install-path <path>  Custom installation directory
+  -k, --token <token>        GitHub token
+  -d, --debug                Enable debug logging
+  -h, --help                 Show this help message
+```
+
+## GitHub Token Verification
+
+The project includes a utility to verify the validity of your GitHub token:
+
+```bash
+check-github-token <token>
+```
+
+If no token is provided as an argument, it will attempt to read from the `GITHUB_TOKEN` environment variable.
+
+## Asset Selection Procedure
+
+The list of assets from the latest release is filtered based on the following rules:
+
+1. If neither `file-name` nor `file-type` is provided, the tool defaults to selecting assets that match the following regular expression: `{{SYSTEM}}[_-]{{ARCH}}.*{{EXT_PATTERN}}$`, where:
+
+    - `{{SYSTEM}}` is replaced with the detected operating system regex.
+    - `{{ARCH}}` is replaced with the detected architecture regex.
+    - `{{EXT_PATTERN}}` is a regex pattern defined by the `file-type` input (defaulting to 'archive' if not specified).
+
+2. If `file-name` is provided literally, the tool uses it directly to match the asset name by using exact string comparison.
+
+3. If `file-name` is provided as a regex pattern (prefixed with `~`), then:
+
+    - If the pattern does not end with `$` and does not include any placeholders, the tool appends `.*{{SYSTEM}}[_-]{{ARCH}}.*{{EXT_PATTERN}}$` to the provided pattern.
+    - If it already ends with `$` or includes all three placeholders, the tool uses it as-is to match the asset name using regex.
+    - If only `{{SYSTEM}}` and `{{ARCH}}` placeholders are included, the tool appends `.*{{EXT_PATTERN}}$`.
+
+4. If `file-type` is not equal to 'archive' or 'package', it is treated as a custom regex pattern to match the file extension.
+
+5. The tool applies the constructed regex pattern to filter the assets from the latest release.
+
+6. If multiple assets match the criteria, the tool fails.
+
+7. After download and extraction, the tool recursively searches for the binary specified by `binary-name` (or the repository name). If found, the directory containing the binary is used as the tool directory and added to the PATH (or used for installation). If the binary is not found, the tool fails.
+
+8. `{{SYSTEM}}` is replaced with the detected operating system regex:
+
+    - For Linux: `linux`.
+    - For MacOS: `(darwin|macos|mac|osx)`.
+    - For Windows: `(windows|win)`.
+
+9. `{{ARCH}}` is replaced with the detected architecture regex:
+
+    - For x64: `(x86_64|x64|amd64)`.
+    - For arm64: `(aarch64|arm64)`.
+
+10. All regular expression matches are case-insensitive.
+
+## License
+
+MIT
 
-> **Important:** Default authentication will will only work if the action is used within GitHub workflow. For Gitea, you must provide a token explicitly.

action.yml

@@ -15,6 +15,10 @@ inputs:
     description: 'The type of the file to be downloaded (archive, package, or custom regex).'
     required: false
     default: 'archive'
+  update-cache:
+    description: 'How to handle the tool cache (false, true, or always). Defaults to false.'
+    required: false
+    default: 'false'
   debug:
     description: 'When set to true, displays the contents of the unpacked archive or directory.'
     required: false

dist/check-token.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+"use strict";var n=require("util");async function i(t,e){let s=`https://api.github.com/repos/${t}/releases/latest`,r={Accept:"application/vnd.github.v3+json","User-Agent":"setup-github-release-action"};e&&(r.Authorization=`token ${e}`);let o=await fetch(s,{headers:r});if(!o.ok){let a=await o.text();throw new Error(`Failed to fetch latest release for ${t}: ${o.statusText}. ${a}`)}return await o.json()}async function c(){let{positionals:t}=(0,n.parseArgs)({allowPositionals:!0}),e=t[0]||process.env.GITHUB_TOKEN;e||(console.error("Error: No GitHub token provided as an argument or found in GITHUB_TOKEN environment variable."),process.exit(1));try{console.log("Verifying GitHub token..."),await i("actions/checkout",e),console.log("\x1B[32mSuccess: The provided GitHub token is valid and has sufficient permissions to access public repositories.\x1B[0m")}catch(s){console.error("\x1B[31mError: GitHub token verification failed.\x1B[0m"),console.error(`Reason: ${s.message}`),process.exit(1)}}c();

dist/cli.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+"use strict";var O=Object.create;var z=Object.defineProperty;var H=Object.getOwnPropertyDescriptor;var U=Object.getOwnPropertyNames;var D=Object.getPrototypeOf,X=Object.prototype.hasOwnProperty;var Y=(t,e,i,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let s of U(e))!X.call(t,s)&&s!==i&&z(t,s,{get:()=>e[s],enumerable:!(r=H(e,s))||r.enumerable});return t};var p=(t,e,i)=>(i=t!=null?O(D(t)):{},Y(e||!t||!t.__esModule?z(i,"default",{value:t,enumerable:!0}):i,t));var F=require("util"),f=p(require("path")),l=p(require("fs")),P=p(require("os"));var T=p(require("os")),G={linux:"linux",darwin:"(darwin|macos|mac|osx)",win32:"(windows|win)"},q={x64:"(x86_64|x64|amd64)",arm64:"(aarch64|arm64)"};function M(){let t=T.platform(),e=T.arch();return{system:t,arch:e,systemPattern:G[t]||t,archPattern:q[e]||e}}function j(t,e,i){let{fileName:r,fileType:s="archive"}=i,o;if(s==="archive"?o="\\.(zip|tar\\.gz|tar|tgz|7z)":s==="package"?o="\\.(deb|rpm|pkg)":o=s,r)if(r.startsWith("~")){let a=r.substring(1),c=a.includes("{{SYSTEM}}"),n=a.includes("{{ARCH}}"),m=a.includes("{{EXT_PATTERN}}"),S=a.endsWith("$");!c&&!n&&!m&&!S?a+=".*{{SYSTEM}}[_-]{{ARCH}}.*{{EXT_PATTERN}}$":c&&n&&!m&&!S&&(a+=".*{{EXT_PATTERN}}$");let h=a.replace(/{{SYSTEM}}/g,e.systemPattern).replace(/{{ARCH}}/g,e.archPattern).replace(/{{EXT_PATTERN}}/g,o),b=new RegExp(h,"i"),u=t.filter(w=>b.test(w.name));if(u.length===0)throw new Error(`No assets matched the regex: ${h}`);if(u.length>1)throw new Error(`Multiple assets matched the criteria: ${u.map(w=>w.name).join(", ")}`);return u[0]}else{let a=t.find(c=>c.name===r);if(!a)throw new Error(`No asset found matching the exact name: ${r}`);return a}else{let a=`${e.systemPattern}[_-]${e.archPattern}.*${o}$`,c=new RegExp(a,"i"),n=t.filter(m=>c.test(m.name));if(n.length===0)throw new Error(`No assets matched the default criteria: ${a}`);if(n.length>1)throw new Error(`Multiple assets matched the default criteria: ${n.map(m=>m.name).join(", ")}`);return n[0]}}var A=p(require("fs")),_=p(require("path"));function I(t,e,i,r){let s=A.readdirSync(t);i&&(r(`Searching for binary in ${t}...`),s.forEach(o=>r(` - ${o}`)));for(let o of s){let a=_.join(t,o);if(A.statSync(a).isDirectory()){let n=I(a,e,i,r);if(n)return n}else{let n=!1;if(e instanceof RegExp?n=e.test(o):(n=o===e,!n&&process.platform==="win32"&&!e.toLowerCase().endsWith(".exe")&&(n=o.toLowerCase()===`${e.toLowerCase()}.exe`)),n)return a}}}async function W(t,e){let i=`https://api.github.com/repos/${t}/releases/latest`,r={Accept:"application/vnd.github.v3+json","User-Agent":"setup-github-release-action"};e&&(r.Authorization=`token ${e}`);let s=await fetch(i,{headers:r});if(!s.ok){let o=await s.text();throw new Error(`Failed to fetch latest release for ${t}: ${s.statusText}. ${o}`)}return await s.json()}async function L(t,e,i){let r={"User-Agent":"setup-github-release-action"};i&&(r.Authorization=`token ${i}`);let s=await fetch(t,{headers:r});if(!s.ok)throw new Error(`Failed to download asset: ${s.statusText}`);let o=await import("fs"),{Readable:a}=await import("stream"),{finished:c}=await import("stream/promises"),n=o.createWriteStream(e);await c(a.fromWeb(s.body).pipe(n))}var x=require("child_process"),y=p(require("path")),E=p(require("fs"));async function B(t,e){let i=y.extname(t).toLowerCase(),r=y.basename(t).toLowerCase();if(E.existsSync(e)||E.mkdirSync(e,{recursive:!0}),r.endsWith(".tar.gz")||r.endsWith(".tgz")||r.endsWith(".tar")){let o=(0,x.spawnSync)("tar",["-xf",t,"-C",e]);if(o.status!==0)throw new Error(`tar failed with status ${o.status}: ${o.stderr.toString()}`)}else if(r.endsWith(".zip"))if(process.platform==="win32"){if((0,x.spawnSync)("tar",["-xf",t,"-C",e]).status===0)return;let o=t.replace(/'/g,"''"),a=e.replace(/'/g,"''"),c=`Add-Type -AssemblyName System.IO.Compression.FileSystem; [System.IO.Compression.ZipFile]::ExtractToDirectory('${o}', '${a}')`;for(let n of["pwsh","powershell"])if((0,x.spawnSync)(n,["-NoProfile","-ExecutionPolicy","Bypass","-Command",c]).status===0)return;throw new Error("Extraction failed: Both tar and PowerShell fallback failed. Make sure your system can extract ZIP files.")}else{let s=(0,x.spawnSync)("unzip",["-q",t,"-d",e]);if(s.status!==0)throw new Error(`unzip failed with status ${s.status}: ${s.stderr.toString()}`)}else if(r.endsWith(".7z")){let s=(0,x.spawnSync)("7z",["x",t,`-o${e}`,"-y"]);if(s.status!==0)throw new Error(`7z failed with status ${s.status}. Make sure 7z is installed.`)}else{let s=y.join(e,y.basename(t));E.copyFileSync(t,s)}}async function Z(){let{values:t,positionals:e}=(0,F.parseArgs)({options:{"file-name":{type:"string",short:"f"},"binary-name":{type:"string",short:"b"},"file-type":{type:"string",short:"t",default:"archive"},"install-path":{type:"string",short:"p"},token:{type:"string",short:"k"},debug:{type:"boolean",short:"d",default:!1},help:{type:"boolean",short:"h"}},allowPositionals:!0});(t.help||e.length===0)&&(console.log(`
+Usage: install-github-release [options] <repository>
+
+Arguments:
+  repository                 The GitHub repository (owner/repo)
+
+Options:
+  -f, --file-name <name>     Asset file name or regex pattern (prefixed with ~)
+  -b, --binary-name <name>   Binary to search for (prefixed with ~ for regex)
+  -t, --file-type <type>     'archive', 'package', or custom regex (default: archive)
+  -p, --install-path <path>  Custom installation directory
+  -k, --token <token>        GitHub token
+  -d, --debug                Enable debug logging
+  -h, --help                 Show this help message
+    `),process.exit(0));let i=e[0];i||(console.error("Error: Repository is required."),process.exit(1));let r=t["file-name"],s=t["binary-name"],o=t["file-type"],a=!!t.debug,c=t.token||process.env.GITHUB_TOKEN;try{let n=M(),m=i.split("/").pop()||i;console.log(`Fetching latest release for ${i}...`);let S=await W(i,c),h=j(S.assets,n,{fileName:r,fileType:o});console.log(`Selected asset: ${h.name}`);let b=l.mkdtempSync(f.join(P.tmpdir(),"setup-gh-release-")),u=f.join(b,h.name);console.log(`Downloading ${h.name}...`),await L(h.browser_download_url,u,c);let w=f.join(b,"extract");console.log(`Extracting ${h.name}...`),await B(u,w);let R=s||m,k;R.startsWith("~")?k=new RegExp(R.substring(1),"i"):k=R;let C=I(w,k,a,console.log);if(!C)throw new Error(`Could not find binary "${R}" in the extracted asset.`);let g;if(t["install-path"])g=f.resolve(t["install-path"]);else if(process.platform==="win32"){let d=process.env.LOCALAPPDATA||f.join(P.homedir(),"AppData","Local");g=f.join(d,"bin")}else if(process.getuid&&process.getuid()===0)g="/usr/local/bin";else{let N=f.join(P.homedir(),"bin");l.existsSync(N)?g=N:g="/usr/local/bin"}l.existsSync(g)||l.mkdirSync(g,{recursive:!0});let v=f.basename(C),$=f.join(g,v);console.log(`Installing ${v} to ${$}...`);try{l.copyFileSync(C,$)}catch(d){throw d.code==="EBUSY"?new Error(`The file ${$} is currently in use. Please close any running instances and try again.`):d.code==="EACCES"||d.code==="EPERM"?new Error(`Permission denied while installing to ${$}. Try running with sudo or as administrator, or use -p to specify a custom path.`):d}process.platform!=="win32"&&l.chmodSync($,"755"),l.rmSync(b,{recursive:!0,force:!0}),console.log("Installation successful!")}catch(n){console.error(`Error: ${n.message}`),process.exit(1)}}Z();

package.json

@@ -1,10 +1,17 @@
 {
-  "name": "setup-github-release",
+  "name": "install-github-release",
   "version": "1.0.0",
-  "description": "A GitHub Action to download a tool",
+  "description": "A GitHub Action and CLI tool to download and install binaries from GitHub releases",
   "main": "dist/index.js",
+  "bin": {
+    "install-github-release": "dist/cli.js",
+    "check-github-token": "dist/check-token.js"
+  },
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --target=node24 --outfile=dist/index.js --minify",
+    "build:action": "esbuild src/index.ts --bundle --platform=node --target=node24 --outfile=dist/index.js --minify",
+    "build:cli": "esbuild src/cli.ts --bundle --platform=node --target=node24 --outfile=dist/cli.js --minify --banner:js=\"#!/usr/bin/env node\"",
+    "build:check-token": "esbuild src/check-token.ts --bundle --platform=node --target=node24 --outfile=dist/check-token.js --minify --banner:js=\"#!/usr/bin/env node\"",
+    "build": "npm run build:action && npm run build:cli && npm run build:check-token",
     "format": "prettier --write '**/*.ts'",
     "format-check": "prettier --check '**/*.ts'",
     "lint": "eslint src/**/*.ts",

src/check-token.ts

@@ -0,0 +1,29 @@
+import { parseArgs } from 'util';
+import { fetchLatestRelease } from './core/downloader';
+
+async function run() {
+  const { positionals } = parseArgs({
+    allowPositionals: true
+  });
+
+  const token = positionals[0] || process.env.GITHUB_TOKEN;
+
+  if (!token) {
+    console.error('Error: No GitHub token provided as an argument or found in GITHUB_TOKEN environment variable.');
+    process.exit(1);
+  }
+
+  try {
+    console.log('Verifying GitHub token...');
+    // Attempt to list latest release of actions/checkout as a test
+    await fetchLatestRelease('actions/checkout', token);
+
+    console.log('\x1b[32mSuccess: The provided GitHub token is valid and has sufficient permissions to access public repositories.\x1b[0m');
+  } catch (error: any) {
+    console.error('\x1b[31mError: GitHub token verification failed.\x1b[0m');
+    console.error(`Reason: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+run();

src/cli.ts

@@ -0,0 +1,151 @@
+import { parseArgs } from 'util';
+import * as path from 'path';
+import * as fs from 'fs';
+import * as os from 'os';
+import { getPlatformInfo } from './core/platform';
+import { getMatchingAsset } from './core/matcher';
+import { findBinary } from './core/finder';
+import { fetchLatestRelease, downloadAsset } from './core/downloader';
+import { extractAsset } from './core/extractor';
+
+async function run() {
+  const { values, positionals } = parseArgs({
+    options: {
+      'file-name': { type: 'string', short: 'f' },
+      'binary-name': { type: 'string', short: 'b' },
+      'file-type': { type: 'string', short: 't', default: 'archive' },
+      'install-path': { type: 'string', short: 'p' },
+      'token': { type: 'string', short: 'k' },
+      'debug': { type: 'boolean', short: 'd', default: false },
+      'help': { type: 'boolean', short: 'h' }
+    },
+    allowPositionals: true
+  });
+
+  if (values.help || positionals.length === 0) {
+    console.log(`
+Usage: install-github-release [options] <repository>
+
+Arguments:
+  repository                 The GitHub repository (owner/repo)
+
+Options:
+  -f, --file-name <name>     Asset file name or regex pattern (prefixed with ~)
+  -b, --binary-name <name>   Binary to search for (prefixed with ~ for regex)
+  -t, --file-type <type>     'archive', 'package', or custom regex (default: archive)
+  -p, --install-path <path>  Custom installation directory
+  -k, --token <token>        GitHub token
+  -d, --debug                Enable debug logging
+  -h, --help                 Show this help message
+    `);
+    process.exit(0);
+  }
+
+  const repository = positionals[0];
+  if (!repository) {
+    console.error('Error: Repository is required.');
+    process.exit(1);
+  }
+
+  const fileNameInput = values['file-name'];
+  const binaryInput = values['binary-name'];
+  const fileType = values['file-type'];
+  const debug = !!values.debug;
+  const token = values.token || process.env.GITHUB_TOKEN;
+
+  try {
+    const platformInfo = getPlatformInfo();
+    const toolName = repository.split('/').pop() || repository;
+
+    console.log(`Fetching latest release for ${repository}...`);
+    const release = await fetchLatestRelease(repository, token);
+    const asset = getMatchingAsset(release.assets, platformInfo, {
+      fileName: fileNameInput,
+      fileType: fileType
+    });
+
+    console.log(`Selected asset: ${asset.name}`);
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'setup-gh-release-'));
+    const downloadPath = path.join(tempDir, asset.name);
+
+    console.log(`Downloading ${asset.name}...`);
+    await downloadAsset(asset.browser_download_url, downloadPath, token);
+
+    const extractDir = path.join(tempDir, 'extract');
+    console.log(`Extracting ${asset.name}...`);
+    await extractAsset(downloadPath, extractDir);
+
+    const binaryName = binaryInput || toolName;
+    let binaryPattern: string | RegExp;
+    if (binaryName.startsWith('~')) {
+      binaryPattern = new RegExp(binaryName.substring(1), 'i');
+    } else {
+      binaryPattern = binaryName;
+    }
+
+    const binaryPath = findBinary(extractDir, binaryPattern, debug, console.log);
+    if (!binaryPath) {
+      throw new Error(`Could not find binary "${binaryName}" in the extracted asset.`);
+    }
+
+    // Determine install directory
+    let installDir: string;
+
+    if (values['install-path']) {
+      installDir = path.resolve(values['install-path']);
+    } else {
+      if (process.platform === 'win32') {
+        const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+        installDir = path.join(localAppData, 'bin');
+      } else {
+        const isRoot = process.getuid && process.getuid() === 0;
+
+        if (isRoot) {
+          installDir = '/usr/local/bin';
+        } else {
+          const homeBin = path.join(os.homedir(), 'bin');
+          if (fs.existsSync(homeBin)) {
+            installDir = homeBin;
+          } else {
+            installDir = '/usr/local/bin';
+          }
+        }
+      }
+    }
+
+    if (!fs.existsSync(installDir)) {
+      fs.mkdirSync(installDir, { recursive: true });
+    }
+
+    const finalName = path.basename(binaryPath);
+    const destPath = path.join(installDir, finalName);
+
+    console.log(`Installing ${finalName} to ${destPath}...`);
+    try {
+      fs.copyFileSync(binaryPath, destPath);
+    } catch (err: any) {
+      if (err.code === 'EBUSY') {
+        throw new Error(`The file ${destPath} is currently in use. Please close any running instances and try again.`);
+      }
+      if (err.code === 'EACCES' || err.code === 'EPERM') {
+        throw new Error(`Permission denied while installing to ${destPath}. Try running with sudo or as administrator, or use -p to specify a custom path.`);
+      }
+      throw err;
+    }
+
+    if (process.platform !== 'win32') {
+      fs.chmodSync(destPath, '755');
+    }
+
+    // Cleanup
+    fs.rmSync(tempDir, { recursive: true, force: true });
+
+    console.log('Installation successful!');
+
+  } catch (error: any) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+run();

src/core/downloader.ts

@@ -0,0 +1,52 @@
+import { getMatchingAsset } from './matcher';
+import { PlatformInfo } from './platform';
+
+export interface ReleaseAsset {
+  name: string;
+  browser_download_url: string;
+}
+
+export interface ReleaseInfo {
+  tag_name: string;
+  assets: ReleaseAsset[];
+}
+
+export async function fetchLatestRelease(repository: string, token?: string): Promise<ReleaseInfo> {
+  const url = `https://api.github.com/repos/${repository}/releases/latest`;
+  const headers: Record<string, string> = {
+    'Accept': 'application/vnd.github.v3+json',
+    'User-Agent': 'setup-github-release-action'
+  };
+  if (token) {
+    headers['Authorization'] = `token ${token}`;
+  }
+
+  const response = await fetch(url, { headers });
+  if (!response.ok) {
+    const errorBody = await response.text();
+    throw new Error(`Failed to fetch latest release for ${repository}: ${response.statusText}. ${errorBody}`);
+  }
+
+  return await response.json() as ReleaseInfo;
+}
+
+export async function downloadAsset(url: string, destPath: string, token?: string): Promise<void> {
+  const headers: Record<string, string> = {
+    'User-Agent': 'setup-github-release-action'
+  };
+  if (token) {
+    headers['Authorization'] = `token ${token}`;
+  }
+
+  const response = await fetch(url, { headers });
+  if (!response.ok) {
+    throw new Error(`Failed to download asset: ${response.statusText}`);
+  }
+
+  const fs = await import('fs');
+  const { Readable } = await import('stream');
+  const { finished } = await import('stream/promises');
+
+  const fileStream = fs.createWriteStream(destPath);
+  await finished(Readable.fromWeb(response.body as any).pipe(fileStream));
+}

src/core/extractor.ts

@@ -0,0 +1,54 @@
+import { spawnSync } from 'child_process';
+import * as path from 'path';
+import * as fs from 'fs';
+
+export async function extractAsset(filePath: string, destDir: string): Promise<void> {
+  const ext = path.extname(filePath).toLowerCase();
+  const name = path.basename(filePath).toLowerCase();
+
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+
+  if (name.endsWith('.tar.gz') || name.endsWith('.tgz') || name.endsWith('.tar')) {
+    const args = ['-xf', filePath, '-C', destDir];
+    const result = spawnSync('tar', args);
+    if (result.status !== 0) {
+      throw new Error(`tar failed with status ${result.status}: ${result.stderr.toString()}`);
+    }
+  } else if (name.endsWith('.zip')) {
+    if (process.platform === 'win32') {
+      // Modern Windows 10/11 has tar that handles zip
+      const tarResult = spawnSync('tar', ['-xf', filePath, '-C', destDir]);
+      if (tarResult.status === 0) return;
+
+      // Fallback: Use .NET ZipFile class to bypass PowerShell module trust issues (Microsoft.PowerShell.Archive)
+      // We escape single quotes for PowerShell.
+      const escapedFilePath = filePath.replace(/'/g, "''");
+      const escapedDestDir = destDir.replace(/'/g, "''");
+      const dotNetCommand = `Add-Type -AssemblyName System.IO.Compression.FileSystem; [System.IO.Compression.ZipFile]::ExtractToDirectory('${escapedFilePath}', '${escapedDestDir}')`;
+
+      // Try pwsh (PowerShell 7) then powershell (Windows PowerShell)
+      for (const shell of ['pwsh', 'powershell']) {
+        const result = spawnSync(shell, ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', dotNetCommand]);
+        if (result.status === 0) return;
+      }
+
+      throw new Error(`Extraction failed: Both tar and PowerShell fallback failed. Make sure your system can extract ZIP files.`);
+    } else {
+      const result = spawnSync('unzip', ['-q', filePath, '-d', destDir]);
+      if (result.status !== 0) {
+        throw new Error(`unzip failed with status ${result.status}: ${result.stderr.toString()}`);
+      }
+    }
+  } else if (name.endsWith('.7z')) {
+      const result = spawnSync('7z', ['x', filePath, `-o${destDir}`, '-y']);
+      if (result.status !== 0) {
+        throw new Error(`7z failed with status ${result.status}. Make sure 7z is installed.`);
+      }
+  } else {
+    // For other files, we just copy them to the destination directory
+    const destPath = path.join(destDir, path.basename(filePath));
+    fs.copyFileSync(filePath, destPath);
+  }
+}

src/core/finder.ts

@@ -0,0 +1,38 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export function findBinary(dir: string, pattern: string | RegExp, debug: boolean, logger: (msg: string) => void): string | undefined {
+  const items = fs.readdirSync(dir);
+  if (debug) {
+    logger(`Searching for binary in ${dir}...`);
+    items.forEach(item => logger(` - ${item}`));
+  }
+
+  for (const item of items) {
+    const fullPath = path.join(dir, item);
+    const stat = fs.statSync(fullPath);
+    if (stat.isDirectory()) {
+      const found = findBinary(fullPath, pattern, debug, logger);
+      if (found) return found;
+    } else {
+      let isMatch = false;
+      if (pattern instanceof RegExp) {
+        isMatch = pattern.test(item);
+      } else {
+        isMatch = item === pattern;
+        // On Windows, also check for .exe extension if the pattern doesn't have it
+        if (!isMatch && process.platform === 'win32' && !pattern.toLowerCase().endsWith('.exe')) {
+          isMatch = item.toLowerCase() === `${pattern.toLowerCase()}.exe`;
+        }
+      }
+      if (isMatch) return fullPath;
+    }
+  }
+  return undefined;
+}
+
+export function setExecutable(filePath: string): void {
+  if (process.platform !== 'win32') {
+    fs.chmodSync(filePath, '755');
+  }
+}

src/core/matcher.ts

@@ -0,0 +1,67 @@
+import { PlatformInfo } from './platform';
+
+export interface MatchOptions {
+  fileName?: string;
+  fileType?: string;
+}
+
+export function getMatchingAsset(assets: any[], platform: PlatformInfo, options: MatchOptions): any {
+  const { fileName, fileType = 'archive' } = options;
+  let extPattern: string;
+  if (fileType === 'archive') {
+    extPattern = '\\.(zip|tar\\.gz|tar|tgz|7z)';
+  } else if (fileType === 'package') {
+    extPattern = '\\.(deb|rpm|pkg)';
+  } else {
+    extPattern = fileType;
+  }
+
+  if (!fileName) {
+    // Rule 1: Default matching rule
+    const pattern = `${platform.systemPattern}[_-]${platform.archPattern}.*${extPattern}$`;
+    const regex = new RegExp(pattern, 'i');
+    const matchingAssets = assets.filter((a: any) => regex.test(a.name));
+    if (matchingAssets.length === 0) {
+      throw new Error(`No assets matched the default criteria: ${pattern}`);
+    }
+    if (matchingAssets.length > 1) {
+      throw new Error(`Multiple assets matched the default criteria: ${matchingAssets.map((a: any) => a.name).join(', ')}`);
+    }
+    return matchingAssets[0];
+  } else if (fileName.startsWith('~')) {
+    // Rule 3: Regex matching rule
+    let pattern = fileName.substring(1);
+    const hasSystem = pattern.includes('{{SYSTEM}}');
+    const hasArch = pattern.includes('{{ARCH}}');
+    const hasExt = pattern.includes('{{EXT_PATTERN}}');
+    const hasEnd = pattern.endsWith('$');
+
+    if (!hasSystem && !hasArch && !hasExt && !hasEnd) {
+      pattern += `.*{{SYSTEM}}[_-]{{ARCH}}.*{{EXT_PATTERN}}$`;
+    } else if (hasSystem && hasArch && !hasExt && !hasEnd) {
+      pattern += `.*{{EXT_PATTERN}}$`;
+    }
+
+    const finalPattern = pattern
+      .replace(/{{SYSTEM}}/g, platform.systemPattern)
+      .replace(/{{ARCH}}/g, platform.archPattern)
+      .replace(/{{EXT_PATTERN}}/g, extPattern);
+
+    const regex = new RegExp(finalPattern, 'i');
+    const matchingAssets = assets.filter((a: any) => regex.test(a.name));
+    if (matchingAssets.length === 0) {
+      throw new Error(`No assets matched the regex: ${finalPattern}`);
+    }
+    if (matchingAssets.length > 1) {
+      throw new Error(`Multiple assets matched the criteria: ${matchingAssets.map((a: any) => a.name).join(', ')}`);
+    }
+    return matchingAssets[0];
+  } else {
+    // Rule 2: Literal matching rule
+    const asset = assets.find((a: any) => a.name === fileName);
+    if (!asset) {
+      throw new Error(`No asset found matching the exact name: ${fileName}`);
+    }
+    return asset;
+  }
+}

src/core/platform.ts

@@ -0,0 +1,31 @@
+import * as os from 'os';
+
+export interface PlatformInfo {
+  system: string;
+  arch: string;
+  systemPattern: string;
+  archPattern: string;
+}
+
+export const systemPatterns: Record<string, string> = {
+  linux: 'linux',
+  darwin: '(darwin|macos|mac|osx)',
+  win32: '(windows|win)'
+};
+
+export const archPatterns: Record<string, string> = {
+  x64: '(x86_64|x64|amd64)',
+  arm64: '(aarch64|arm64)'
+};
+
+export function getPlatformInfo(): PlatformInfo {
+  const system = os.platform();
+  const arch = os.arch();
+
+  return {
+    system,
+    arch,
+    systemPattern: systemPatterns[system] || system,
+    archPattern: archPatterns[arch] || arch
+  };
+}

src/index.ts

@@ -3,159 +3,66 @@ import * as tc from '@actions/tool-cache';
 import * as path from 'path';
 import * as os from 'os';
 import * as fs from 'fs';
-
-function findBinary(dir: string, pattern: string | RegExp, debug: boolean): string | undefined {
-  const items = fs.readdirSync(dir);
-  if (debug) {
-    core.info(`Searching for binary in ${dir}...`);
-    items.forEach(item => core.info(` - ${item}`));
-  }
-
-  for (const item of items) {
-    const fullPath = path.join(dir, item);
-    const stat = fs.statSync(fullPath);
-    if (stat.isDirectory()) {
-      const found = findBinary(fullPath, pattern, debug);
-      if (found) return found;
-    } else {
-      let isMatch = false;
-      if (pattern instanceof RegExp) {
-        isMatch = pattern.test(item);
-      } else {
-        isMatch = item === pattern;
-        // On Windows, also check for .exe extension if the pattern doesn't have it
-        if (!isMatch && process.platform === 'win32' && !pattern.toLowerCase().endsWith('.exe')) {
-          isMatch = item.toLowerCase() === `${pattern.toLowerCase()}.exe`;
-        }
-      }
-      if (isMatch) return fullPath;
-    }
-  }
-  return undefined;
-}
+import { getPlatformInfo } from './core/platform';
+import { getMatchingAsset } from './core/matcher';
+import { findBinary } from './core/finder';
+import { fetchLatestRelease } from './core/downloader';
 
 async function run() {
   try {
     const repository = core.getInput('repository', { required: true });
-    let fileName = core.getInput('file-name');
+    const fileNameInput = core.getInput('file-name');
     const binaryInput = core.getInput('binary-name');
     const fileType = core.getInput('file-type') || 'archive';
+    const updateCache = core.getInput('update-cache') || 'false';
     const debug = core.getBooleanInput('debug');
     const token = core.getInput('token') || process.env.GITHUB_TOKEN;
 
-    // Detect system and architecture
-    const platform = os.platform(); // 'linux', 'darwin', 'win32'
-    const arch = os.arch(); // 'x64', 'arm64'
+    const platformInfo = getPlatformInfo();
+    const toolName = repository.split('/').pop() || repository;
 
-    const systemPatterns: Record<string, string> = {
-      linux: 'linux',
-      darwin: '(darwin|macos|mac)',
-      win32: '(windows|win)'
-    };
-
-    const archPatterns: Record<string, string> = {
-      x64: '(x86_64|x64|amd64)',
-      arm64: '(aarch64|arm64)'
-    };
-
-    const systemPattern = systemPatterns[platform] || platform;
-    const archPattern = archPatterns[arch] || arch;
-
-    let extPattern: string;
-    if (fileType === 'archive') {
-      extPattern = '\\.(zip|tar\\.gz|tar|tgz|7z)';
-    } else if (fileType === 'package') {
-      extPattern = '\\.(deb|rpm|pkg)';
-    } else {
-      extPattern = fileType;
-    }
-
-    const url = `https://api.github.com/repos/${repository}/releases/latest`;
-    const headers: Record<string, string> = {
-      'Accept': 'application/vnd.github.v3+json',
-      'User-Agent': 'setup-github-release-action'
-    };
-    if (token) {
-      headers['Authorization'] = `token ${token}`;
+    // Rule for update-cache: 'false' means use ANY cached version if available
+    if (updateCache === 'false') {
+      const allVersions = tc.findAllVersions(toolName, platformInfo.arch);
+      if (allVersions.length > 0) {
+        const latestVersion = allVersions.sort().pop();
+        if (latestVersion) {
+          const cachedDir = tc.find(toolName, latestVersion, platformInfo.arch);
+          if (cachedDir) {
+            core.info(`Found ${toolName} version ${latestVersion} in local cache (update-cache: false)`);
+            core.addPath(cachedDir);
+            return;
+          }
+        }
+      }
     }
 
     core.info(`Fetching latest release information for ${repository}...`);
-    const response = await fetch(url, { headers });
-    if (!response.ok) {
-      throw new Error(`Failed to fetch release: ${response.statusText} (${response.status})`);
-    }
+    const release = await fetchLatestRelease(repository, token);
+    const asset = getMatchingAsset(release.assets, platformInfo, {
+      fileName: fileNameInput,
+      fileType: fileType
+    });
 
-    const data: any = await response.json();
-    let asset;
+    core.info(`Selected asset: ${asset.name}`);
 
-    if (!fileName) {
-      // Rule 1: Default matching rule
-      const pattern = `${systemPattern}[_-]${archPattern}.*${extPattern}$`;
-      const regex = new RegExp(pattern, 'i');
-      core.info(`No file-name provided. Using default pattern: ${pattern}`);
-      const matchingAssets = data.assets.filter((a: any) => regex.test(a.name));
-      if (matchingAssets.length === 0) {
-        throw new Error(`No assets matched the default criteria: ${pattern}`);
-      }
-      if (matchingAssets.length > 1) {
-        throw new Error(`Multiple assets matched the default criteria: ${matchingAssets.map((a: any) => a.name).join(', ')}`);
-      }
-      asset = matchingAssets[0];
-    } else if (fileName.startsWith('~')) {
-      // Rule 3: Regex matching rule
-      let pattern = fileName.substring(1);
-      const hasSystem = pattern.includes('{{SYSTEM}}');
-      const hasArch = pattern.includes('{{ARCH}}');
-      const hasExt = pattern.includes('{{EXT_PATTERN}}');
-      const hasEnd = pattern.endsWith('$');
-
-      if (!hasSystem && !hasArch && !hasExt && !hasEnd) {
-        pattern += `.*{{SYSTEM}}[_-]{{ARCH}}.*{{EXT_PATTERN}}$`;
-      } else if (hasSystem && hasArch && !hasExt && !hasEnd) {
-        pattern += `.*{{EXT_PATTERN}}$`;
-      }
-
-      const finalPattern = pattern
-        .replace(/{{SYSTEM}}/g, systemPattern)
-        .replace(/{{ARCH}}/g, archPattern)
-        .replace(/{{EXT_PATTERN}}/g, extPattern);
-
-      const regex = new RegExp(finalPattern, 'i');
-      core.info(`Using regex pattern: ${finalPattern}`);
-      const matchingAssets = data.assets.filter((a: any) => regex.test(a.name));
-      if (matchingAssets.length === 0) {
-        throw new Error(`No assets matched the regex: ${finalPattern}`);
-      }
-      if (matchingAssets.length > 1) {
-        throw new Error(`Multiple assets matched the criteria: ${matchingAssets.map((a: any) => a.name).join(', ')}`);
-      }
-      asset = matchingAssets[0];
-    } else {
-      // Literal matching rule
-      core.info(`Using literal match for: ${fileName}`);
-      asset = data.assets.find((a: any) => a.name === fileName);
-    }
-
-    if (!asset) {
-      throw new Error(`No asset found matching the criteria in release ${data.tag_name}`);
-    }
-
-    const version = data.tag_name.replace(/^v/, '');
-    const toolName = repository.split('/').pop() || repository;
+    const version = release.tag_name.replace(/^v/, '');
     const binaryName = binaryInput || toolName;
 
-    // Check if the tool is already in the cache
-    const cachedDir = tc.find(toolName, version, arch);
-    if (cachedDir) {
-      core.info(`Found ${toolName} version ${version} in cache at ${cachedDir}`);
-      core.addPath(cachedDir);
-      return;
+    // Check if the tool is already in the cache (if not 'always' update)
+    if (updateCache !== 'always') {
+      const cachedDir = tc.find(toolName, version, platformInfo.arch);
+      if (cachedDir) {
+        core.info(`Found ${toolName} version ${version} in cache at ${cachedDir}`);
+        core.addPath(cachedDir);
+        return;
+      }
     }
 
     const downloadUrl = asset.browser_download_url;
     core.info(`Downloading ${asset.name} from ${downloadUrl}...`);
 
-    const downloadPath = await tc.downloadTool(downloadUrl);
+    const downloadPath = await tc.downloadTool(downloadUrl, undefined, token ? `token ${token}` : undefined);
 
     const nameLower = asset.name.toLowerCase();
     let toolDir: string;
@@ -179,7 +86,6 @@ async function run() {
       }
       fs.renameSync(downloadPath, destPath);
 
-      // Make it executable on Linux/macOS
       if (process.platform !== 'win32') {
         fs.chmodSync(destPath, '755');
       }
@@ -195,14 +101,14 @@ async function run() {
       core.info(`Searching for binary named: ${binaryName}`);
     }
 
-    const binaryPath = findBinary(toolDir, binaryPattern, debug);
+    const binaryPath = findBinary(toolDir, binaryPattern, debug, (msg) => core.info(msg));
     if (!binaryPath) {
       throw new Error(`Could not find binary "${binaryName}" in the extracted asset.`);
     }
 
     // The tool directory is the one containing the binary
     toolDir = path.dirname(binaryPath);
-    core.info(`Binary found at ${binaryPath}. Setting tool directory to ${toolDir}`);
+    core.info(`Binary found at ${binaryPath}.`);
 
     // Make binary executable just in case it's not
     if (process.platform !== 'win32') {
@@ -210,7 +116,7 @@ async function run() {
     }
 
     // Cache the tool
-    const finalCachedDir = await tc.cacheDir(toolDir, toolName, version, arch);
+    const finalCachedDir = await tc.cacheDir(toolDir, toolName, version, platformInfo.arch);
     core.info(`Cached ${toolName} version ${version} to ${finalCachedDir}`);
 
     core.addPath(finalCachedDir);