Further updates:

- Apache 2.0 copyright
- Address review comments
- Use yarn cache for tool downloads
- Check tool sha256 if available

Author: Your Name

.github/workflows/ci.yml

@@ -73,6 +73,7 @@ jobs:
         uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
         with:
           name: dist
+          path: dist
 
       - name: Cache tools
         uses: actions/cache@0c907a75c2c80ebcb7f088228285e798b750cf8f # v4.2.6

.vscodeignore

@@ -14,3 +14,4 @@ webpack.config.js
 scripts
 tools/**/version.txt
 tools/**/target.txt
+tools/**/sha256.txt

DEVELOPMENT.md

@@ -67,3 +67,15 @@ Supported `<target>`s are:
     ```
 
     **Note**: At this point, no tests have been added to this repository.
+
+## Updating tool dependencies
+
+Tool dependencies are recorded in `package.json`:
+
+```json
+  "cmsis": {
+    "<tool>": "[<owner>/<repo>@]<version>"
+  }
+````
+
+The `<version>` must match the tools release version tag.

eslint.config.mjs

@@ -21,6 +21,7 @@ export default [
     {
         ignores: [
             "dist",
+            "scripts",
             "**/*.d.ts",
             "jest.config.js",
             "node_modules",

package.json

@@ -223,7 +223,7 @@
   "scripts": {
     "prepare": "yarn run build",
     "download-tools": "ts-node scripts/download-tools.ts",
-    "clean": "git clean -f -x ./node_modules ./dist ./coverage",
+    "clean": "git clean -f -x ./node_modules ./dist ./coverage ./tools",
     "build": "webpack --mode production && yarn lint",
     "watch": "webpack -w",
     "lint": "eslint .",
@@ -259,6 +259,6 @@
     "yargs": "^17.7.2"
   },
   "cmsis": {
-    "pyocd": "0.0.0-standalone"
+    "pyocd": "MatthiasHertel80/pyOCD@0.0.0-standalone-cbuild1"
   }
 }

scripts/download-tools.ts

@@ -1,20 +1,39 @@
 #!npx ts-node
 
-/*
- * Copyright (C) 2025 Arm Limited
+/**
+ * Copyright 2025 Arm Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
  */
 
 import nodeOs from 'os';
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import path from 'path';
 import { downloadFile } from './file-download';
 import yargs from 'yargs';
 import extractZip from 'extract-zip';
+import { execSync } from 'child_process';
 
 // OS/architecture pairs from vsce --publish
 type VsceTarget = 'win32-x64' | 'win32-arm64' | 'linux-x64' | 'linux-arm64' | 'darwin-x64' | 'darwin-arm64';
 const VSCE_TARGETS = ['win32-x64', 'win32-arm64', 'linux-x64', 'linux-arm64', 'darwin-x64', 'darwin-arm64'] as const;
 
+type Repo = { repo: string };
+type Owner = { owner: string };
+type Token = { token: string };
+
+type ToolOptions = { token?: string, cache?: string };
+
 const TOOLS = {
     'pyocd': downloadPyOCD,
 };
@@ -24,30 +43,105 @@ const PACKAGE_JSON = path.resolve(__dirname, '../package.json');
 function getVersionFromPackageJson(packageJsonPath: string, tool: keyof typeof TOOLS) {
     const packageJsonContent = readFileSync(packageJsonPath, 'utf-8');
     const packageJson = JSON.parse(packageJsonContent);
-    const cmsisConfig = packageJson.cmsis;
-
-    return `${cmsisConfig[tool]}`;
+    return packageJson?.cmsis[tool] as string | undefined;
 }
 
-function getVersionCore(version: string) {
-    return version.split('-')[0];
+function splitGitReleaseVersion(releaseVersion: string, repoAndOwnerDefault: Repo & Owner) {
+    if (releaseVersion.includes('@')) {
+        const parts = releaseVersion.split('@');
+        const version = parts[1];
+        const repoAndOwner = parts[0].split('/');
+        return { repoAndOwner: { owner: repoAndOwner[0], repo: repoAndOwner[1] }, version };
+    }
+    return { repoAndOwner: repoAndOwnerDefault, version: releaseVersion };
 }
 
+
 async function createOktokit(auth?: string) {
     const { Octokit } = await import('octokit');
 
     const { default: nodeFetch } = await import('node-fetch');
     return new Octokit({ auth, request: { fetch: nodeFetch } });
 }
 
-async function downloadPyOCD(target: VsceTarget, dest: string) {
-    const repoAndOwner = { owner: 'MatthiasHertel80', repo: 'pyOCD' } as const;
+async function findGithubReleaseAsset(repo: Repo & Owner & Partial<Token>, version: string, asset_name: string) {
+    const repoAndOwner = { owner: repo.owner, repo: repo.repo };
+    const octokit = await createOktokit(repo.token);
+
+    const releases = (await octokit.rest.repos.listReleases({ ...repoAndOwner })).data;
+    const release = releases.find(r => r.tag_name === `v${version}` || r.tag_name === version);
+
+    if (!release) {
+        throw new Error(`Could not find release for version ${version}`);
+    }
+
+    const assets = (await octokit.rest.repos.listReleaseAssets({ ...repoAndOwner, release_id: release.id })).data;
+    const asset = assets.find(a => a.name === asset_name);
+
+    if (!asset) {
+        throw new Error(`Could not find release asset for version ${version}`);
+    }
+
+    const asset_sha256 = assets.find(a => a.name === `${asset_name}.sha256`);
+
+    return { asset, sha256: asset_sha256 };
+}
+
+async function retrieveSha256(url?: string, token?: string) {
+    if (url) {
+        const tempfile = await import('tempfile');
+        const downloadFilePath = tempfile.default({ extension: '.sha256' });
+        console.debug(`Downloading ${url} ...`);
+        await downloadFile(url, downloadFilePath, token);
+        const sha256 = readFileSync(downloadFilePath, { encoding: 'utf8' });
+        rmSync(downloadFilePath, { force: true });
+        return sha256;
+    }
+    return undefined;
+}
+
+async function download(url: string, options?: ToolOptions & { cache_key?: string }) {
+    const cachePath = (options?.cache && options?.cache_key) ? path.join(options.cache, options.cache_key): undefined;
+    if (cachePath && existsSync(cachePath)) {
+        console.debug(`Found asset in cache ${cachePath} ...`);
+        return { mode: 'cache', path: cachePath};
+    }
+
+    const tempfile = await import('tempfile');
+    const downloadFilePath = tempfile.default({ extension: '.zip' });
+    console.debug(`Downloading ${url} ...`);
+    await downloadFile(url, downloadFilePath, options?.token).catch(error => {
+        throw new Error(`Failed to download ${url}`, { cause: error });
+    });
+
+    const extractPath = cachePath ?? downloadFilePath.replace('.zip', '');
+    console.debug(`Extracting to ${extractPath} ...`);
+    await extractZip(downloadFilePath, { dir: extractPath }).catch(error => {
+        throw new Error(`Failed to extract ${url}`, { cause: error });
+    });
+
+    rmSync(downloadFilePath, { force: true });
+    return { mode: cachePath ? 'cache' : 'temp', path: extractPath };
+}
+
+async function downloadPyOCD(target: VsceTarget, dest: string, options?: ToolOptions) {
+    const repoAndOwnerDefault = { owner: 'MatthiasHertel80', repo: 'pyOCD' } as const;
+    const jsonVersion = getVersionFromPackageJson(PACKAGE_JSON, 'pyocd');
+
+    if (!jsonVersion) {
+        throw new Error('PyOCD version not found in package.json');
+    }
+
+    console.log(`Looking up PyOCD version ${jsonVersion} (${target}) ...`);
+
+    const { repoAndOwner, version } = splitGitReleaseVersion(jsonVersion, repoAndOwnerDefault);
+
     const githubToken = process.env.GITHUB_TOKEN;
     const destPath = path.join(dest, 'pyocd');
     const versionFilePath = path.join(destPath, 'version.txt');
     const targetFilePath = path.join(destPath, 'target.txt');
+    const sha256FilePath = path.join(destPath, 'sha256.txt');
 
-    const version = getVersionFromPackageJson(PACKAGE_JSON, 'pyocd');
     const { os, arch } = {
         'win32-x64': { os: 'windows', arch: '' },
         'win32-arm64': { os: 'windows', arch: '' },
@@ -57,57 +151,53 @@ async function downloadPyOCD(target: VsceTarget, dest: string) {
         'darwin-arm64': { os: 'macos', arch: '' },
     }[target];
 
+    const asset_name = `pyocd-${os}${arch}-${version}.zip`;
+    console.debug(`Looking up GitHub release asset ${repoAndOwner.owner}/${repoAndOwner.repo}/${version}/${asset_name} ...`);
+    const { asset, sha256 } = await findGithubReleaseAsset({ ...repoAndOwner, token: githubToken }, version, asset_name);
+    const sha256sum = await retrieveSha256(sha256?.url, githubToken).catch(error => {
+        console.warn(`Failed to retrieve sha256 sum: ${error}`);
+        return undefined;
+    });
+
     if (existsSync(versionFilePath) && existsSync(targetFilePath)) {
         const hasVersion = readFileSync(versionFilePath, { encoding: 'utf8' });
         const hasTarget = readFileSync(targetFilePath, { encoding: 'utf8' });
-        if (version === hasVersion && target === hasTarget) {
-            console.log(`PyOCD version ${version} (${target}) already available.`);
+        const hasSha256Sum = existsSync(sha256FilePath) ? readFileSync(sha256FilePath, { encoding: 'utf8' }) : undefined;
+
+        if (jsonVersion === hasVersion && target === hasTarget && ((sha256sum === undefined) || (sha256sum === hasSha256Sum))) {
+            console.log(`PyOCD version ${jsonVersion} (${target}) already available.`);
             return;
         }
     }
 
-    console.log(`Downloading PyOCD version ${version} (${target}) ...`);
-
-    const octokit = await createOktokit(githubToken);
-
-    const releases = (await octokit.rest.repos.listReleases(repoAndOwner)).data;
-    const release = releases.find(r => r.tag_name === `v${version}` || r.tag_name === version);
-
-    if (!release) {
-        throw new Error(`Could not find release for version ${version}`);
-    }
-
-    const assets = (await octokit.rest.repos.listReleaseAssets({ ...repoAndOwner, release_id: release.id })).data;
-    const asset = assets.find(a => a.name === `pyocd-${os}${arch}-${getVersionCore(version)}.zip`);
+    const { mode, path: extractPath } = await download(asset.url, { token: githubToken, cache: options?.cache, cache_key: `cmsis-pyocd-${version}-${sha256sum}` });
 
-    if (!asset) {
-        throw new Error(`Could not find release asset for version ${version} and target ${target}`);
+    if (existsSync(destPath)) {
+        console.debug(`Removing existing ${destPath} ...`);
+        rmSync(destPath, { recursive: true, force: true });
     }
 
-    const tempfile = await import('tempfile');
-    const downloadFilePath = tempfile.default({ extension: '.zip' });
-    await downloadFile(asset.url, downloadFilePath, githubToken).catch(error => {
-        throw new Error(`Failed to download PyOCD: ${error}`);
-    });
-
-    const extractPath = downloadFilePath.replace('.zip', '');
-    await extractZip(downloadFilePath, { dir: extractPath }).catch(error => {
-        throw new Error(`Failed to extract PyOCD: ${error}`);
-    });
+    console.debug(`Copying ${extractPath} to ${destPath} ...`);
+    cpSync(extractPath, destPath, { recursive: true, force: true });
 
-    rmSync(downloadFilePath, { force: true });
-
-    if (existsSync(destPath)) {
-        rmSync(destPath, { recursive: true, force: true });
+    if (mode === 'temp') {
+        console.debug(`Removing temporary ${extractPath} ...`);
+        rmSync(extractPath, { recursive: true, force: true });
     }
-    renameSync(extractPath, destPath);
 
-    writeFileSync(versionFilePath, version, { encoding: 'utf8' });
+    writeFileSync(versionFilePath, jsonVersion, { encoding: 'utf8' });
     writeFileSync(targetFilePath, target, { encoding: 'utf8' });
+    if (sha256sum) {
+        writeFileSync(sha256FilePath, sha256sum, { encoding: 'utf8' });
+    }
 }
 
 async function main() {
-    const { target, dest, tools } = yargs
+    // Get Yarn cache directory
+    const yarnCacheDir = execSync('yarn cache dir').toString().trim();
+    console.debug(`Yarn cache directory: ${yarnCacheDir}`);
+
+    const { target, dest, cache, cache_disable, tools } = yargs
         .option('t', {
             alias: 'target',
             description: 'VS Code extension target, defaults to system',
@@ -119,6 +209,16 @@ async function main() {
             description: 'Destination directory for the tools',
             default: path.join(__dirname, '..', 'tools')
         })
+        .option('c', {
+            alias: 'cache',
+            description: 'Directory for caching tool downloads',
+            default: yarnCacheDir
+        })
+        .option('no-cache', {
+            description: 'Disable caching of tool downloads',
+            type: 'boolean',
+            default: false
+        })
         .version(false)
         .strict()
         .command('$0 [<tools> ...]', 'Downloads the tool(s) for the given architecture and OS', y => {
@@ -129,14 +229,14 @@ async function main() {
                 default: Object.keys(TOOLS)
             });
         })
-        .argv as unknown as { target: VsceTarget, dest: string, tools: (keyof typeof TOOLS)[] };
+        .argv as unknown as { target: VsceTarget, dest: string, cache: string, cache_disable: boolean, tools: (keyof typeof TOOLS)[] };
 
     if (!existsSync(dest)) {
         mkdirSync(dest, { recursive: true });
     }
 
     for (const tool of new Set(tools)) {
-        TOOLS[tool](target, dest);
+        TOOLS[tool](target, dest, { cache: cache_disable ? undefined : cache });
     }
 }
 

scripts/file-download.ts

@@ -1,5 +1,17 @@
 /**
- * Copyright (C) 2024 Arm Limited
+ * Copyright 2025 Arm Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
  */
 
 import { createWriteStream } from 'fs';