Merge pull request #1000 from NordicSemiconductor/feat/specify_nrfutil_core_version

Specify core version of nrfutil

Author: datenreisender

Changelog.md

@@ -7,13 +7,24 @@ This project does _not_ adhere to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html) but contrary to it
 every new version is a new major version.
 
+## 212.0.0 - 2025-06-05
+
+### Added
+
+-   Specify what core version of nrfutil an app depends on.
+
+### Steps to upgrade when using this package
+
+-   In apps in `package.json` set the field `nrfConnectForDesktop.nrfutilCore`
+    to the core version of nrfutil that the nrfutil commands will use.
+
 ## 211.0.0 - 2025-05-29
 
 ### Fixed
 
--   It was observed that on mac we get multiple arrive event and the only chnage
-    is the number if serial ports. Now the selected device in redux will also
-    update to reflect these chnages
+-   It was observed on macOS that we get multiple arrive events and the only
+    change is the number of serial ports. Now the selected device in redux is
+    also updated to reflect these changes.
 
 ## 210.0.0 - 2025-05-15
 

ipc/MetaFiles.ts

@@ -22,11 +22,12 @@ export type AppVersions = {
     [version: string]: AppVersion;
 };
 
-export type AppVersion = {
+type AppVersion = {
     shasum?: string;
     publishTimestamp?: string;
     tarballUrl: UrlString;
     nrfutilModules?: NrfutilModules;
+    nrfutilCore?: NrfutilModuleVersion;
 };
 
 export interface AppInfo {
@@ -57,6 +58,9 @@ const nrfutilModuleVersion = semver;
 export type NrfutilModuleName = z.infer<typeof nrfutilModuleName>;
 export type NrfutilModuleVersion = z.infer<typeof nrfutilModuleVersion>;
 
-export const nrfModules = z.record(nrfutilModuleName, z.tuple([semver]));
+export const nrfModules = z.record(
+    nrfutilModuleName,
+    z.tuple([nrfutilModuleVersion])
+);
 
 export type NrfutilModules = z.infer<typeof nrfModules>;

ipc/apps.ts

@@ -5,7 +5,12 @@
  */
 
 import { handle, invoke } from './infrastructure/rendererToMain';
-import type { AppVersions, NrfutilModules, UrlString } from './MetaFiles';
+import type {
+    AppVersions,
+    NrfutilModules,
+    NrfutilModuleVersion,
+    UrlString,
+} from './MetaFiles';
 import { LOCAL, Source, SourceName } from './sources';
 
 export interface AppSpec {
@@ -34,6 +39,7 @@ interface Installed {
     repositoryUrl?: UrlString;
     html?: string;
     nrfutil?: NrfutilModules;
+    nrfutilCore?: NrfutilModuleVersion;
     installed: {
         publishTimestamp?: string;
         path: string;

ipc/schema/packageJson.ts

@@ -26,6 +26,7 @@ export const parsePackageJson = parseWithPrettifiedErrorMessage(packageJson);
 const nrfConnectForDesktop = z.object({
     supportedDevices: z.enum(knownDevicePcas).array().nonempty().optional(),
     nrfutil: nrfModules.optional(),
+    nrfutilCore: semver,
     html: z.string(),
 });
 
@@ -59,11 +60,11 @@ export const parsePackageJsonApp =
     parseWithPrettifiedErrorMessage(packageJsonApp);
 
 // In the launcher we want to handle that the whole nrfConnectForDesktop may be missing
-// and the html in it can also be undefined, so there we need to use this legacy variant
+// and html or nrfutilCore in it can also be undefined, so there we need to use this legacy variant
 const packageJsonLegacyApp = packageJsonApp.extend({
     nrfConnectForDesktop: nrfConnectForDesktop
         .extend({ supportedDevices: z.array(z.string()).nonempty().optional() })
-        .partial({ html: true })
+        .partial({ html: true, nrfutilCore: true })
         .optional(),
 });
 

nrfutil/index.ts

@@ -5,7 +5,7 @@
  */
 
 export { default as prepareSandbox } from './sandbox';
-export { NrfutilSandbox } from './sandbox';
+export type { NrfutilSandbox } from './sandbox';
 export type { Progress } from './sandboxTypes';
 export { getNrfutilLogger, setNrfutilLogger } from './nrfutilLogger';
 export {

nrfutil/moduleVersion.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: LicenseRef-Nordic-4-Clause
  */
 
-import { packageJsonApp } from '../src/utils/packageJson';
+import { isLauncher, packageJsonApp } from '../src/utils/packageJson';
 import {
     type Dependency,
     hasVersion,
@@ -78,11 +78,20 @@ const versionFromPackageJson = (module: string) =>
     packageJsonApp().nrfConnectForDesktop.nrfutil?.[module][0];
 
 const failToDetermineVersion = (module: string) => {
-    throw new Error(`No version specified for the bundled nrfutil ${module}`);
+    throw new Error(`No version specified for nrfutil ${module}`);
 };
 
 export const versionToInstall = (module: string, version?: string) =>
     version ??
     overriddenVersion(module) ??
     versionFromPackageJson(module) ??
     failToDetermineVersion(module);
+
+const coreVersionFromPackageJson = () =>
+    isLauncher()
+        ? undefined // Will lead to using CORE_VERSION_FOR_LEGACY_APPS
+        : packageJsonApp().nrfConnectForDesktop.nrfutilCore ??
+          failToDetermineVersion('core');
+
+export const coreVersionsToInstall = (coreVersion?: string) =>
+    coreVersion ?? overriddenVersion('core') ?? coreVersionFromPackageJson();

nrfutil/sandbox.ts

@@ -13,7 +13,7 @@ import treeKill from 'tree-kill';
 import describeError from '../src/logging/describeError';
 import telemetry from '../src/telemetry/telemetry';
 import { isDevelopment } from '../src/utils/environment';
-import { versionToInstall } from './moduleVersion';
+import { coreVersionsToInstall, versionToInstall } from './moduleVersion';
 import { getNrfutilLogger } from './nrfutilLogger';
 import {
     BackgroundTask,
@@ -40,18 +40,31 @@ const parseJsonBuffers = <T>(data: Buffer): T[] | undefined => {
     }
 };
 
-const nrfutilSandboxFolder =
-    process.platform === 'darwin' && process.arch !== 'x64'
-        ? path.join('nrfutil-sandboxes', process.arch)
-        : 'nrfutil-sandboxes';
-
-const prepareEnv = (baseDir: string, module: string, version: string) => {
+const nrfutilSandboxPathSegments = (
+    baseDir: string,
+    module: string,
+    version: string,
+    coreVersion?: string
+) => [
+    baseDir,
+    'nrfutil-sandboxes',
+    ...(process.platform === 'darwin' && process.arch !== 'x64'
+        ? [process.arch]
+        : []),
+    ...(coreVersion != null ? [coreVersion] : []),
+    module,
+    version,
+];
+
+const prepareEnv = (
+    baseDir: string,
+    module: string,
+    version: string,
+    coreVersion?: string
+) => {
     const env = { ...process.env };
     env.NRFUTIL_HOME = path.join(
-        baseDir,
-        nrfutilSandboxFolder,
-        module,
-        version
+        ...nrfutilSandboxPathSegments(baseDir, module, version, coreVersion)
     );
     fs.mkdirSync(env.NRFUTIL_HOME, { recursive: true });
 
@@ -124,16 +137,25 @@ export class NrfutilSandbox {
     baseDir: string;
     module: string;
     version: string;
+    coreVersion: string | undefined; // Must only be undefined when the launcher creates a sandbox for a legacy app, which does not specify the required core version
     onLoggingHandlers: ((logging: LogMessage, pid?: number) => void)[] = [];
     logLevel: LogLevel = isDevelopment ? 'error' : 'off';
     env: ReturnType<typeof prepareEnv>;
 
-    constructor(baseDir: string, module: string, version: string) {
+    readonly CORE_VERSION_FOR_LEGACY_APPS = '8.0.0';
+
+    constructor(
+        baseDir: string,
+        module: string,
+        version: string,
+        coreVersion?: string
+    ) {
         this.baseDir = baseDir;
         this.module = module;
         this.version = version;
+        this.coreVersion = coreVersion;
 
-        this.env = prepareEnv(baseDir, module, version);
+        this.env = prepareEnv(baseDir, module, version, coreVersion);
     }
 
     private processLoggingData = (data: NrfutilJson, pid?: number) => {
@@ -173,10 +195,12 @@ export class NrfutilSandbox {
         if (
             fs.existsSync(
                 path.join(
-                    this.baseDir,
-                    nrfutilSandboxFolder,
-                    this.module,
-                    this.version,
+                    ...nrfutilSandboxPathSegments(
+                        this.baseDir,
+                        this.module,
+                        this.version,
+                        this.coreVersion
+                    ),
                     'bin',
                     `nrfutil-${this.module}${
                         os.platform() === 'win32' ? '.exe' : ''
@@ -201,15 +225,8 @@ export class NrfutilSandbox {
                     force: true,
                 });
             }
-            await this.updateNrfUtilCore();
-            await this.spawnNrfutil(
-                'install',
-                [`${this.module}=${this.version}`, '--force'],
-                onProgress
-            );
-            getNrfutilLogger()?.info(
-                `Successfully installed nrfutil ${this.module} version: ${this.version}`
-            );
+            await this.installNrfUtilCore(onProgress);
+            await this.installNrfUtilCommand(onProgress);
         } catch (error) {
             if (this.env.NRFUTIL_HOME && fs.existsSync(this.env.NRFUTIL_HOME)) {
                 fs.rmSync(this.env.NRFUTIL_HOME, {
@@ -218,25 +235,61 @@ export class NrfutilSandbox {
                 });
             }
 
-            getNrfutilLogger()?.error(
-                `Error while installing nrfutil ${this.module} version: ${
-                    this.version
-                }. describeError: ${describeError(error)}`
-            );
             throw error;
         }
     };
 
-    public updateNrfUtilCore = async (
+    private installNrfUtilCore = async (
+        onProgress?: (progress: Progress, task?: Task) => void
+    ) => {
+        const currentCoreVersion = await this.getCoreVersion();
+        const requestedCoreVersion =
+            this.coreVersion ?? this.CORE_VERSION_FOR_LEGACY_APPS;
+        if (currentCoreVersion.version === requestedCoreVersion) {
+            getNrfutilLogger()?.debug(
+                `Requested nrfutil core version ${requestedCoreVersion} is already installed.`
+            );
+
+            return;
+        }
+
+        await this.install(
+            'core',
+            requestedCoreVersion,
+            'self-upgrade',
+            ['--to-version', requestedCoreVersion],
+            onProgress
+        );
+    };
+
+    public installNrfUtilCommand = (
         onProgress?: (progress: Progress, task?: Task) => void
+    ) =>
+        this.install(
+            this.module,
+            this.version,
+            'install',
+            [`${this.module}=${this.version}`, '--force'],
+            onProgress
+        );
+
+    public install = async (
+        module: string,
+        version: string,
+        ...args: Parameters<typeof this.spawnNrfutil>
     ) => {
         try {
-            await this.spawnNrfutil('self-upgrade', [], onProgress);
-        } catch (error) {
-            // User might not have internet hance fail silently
-            getNrfutilLogger()?.error(
-                `Error while updating the bundled core for nrfutil ${this.module}.`
+            await this.spawnNrfutil(...args);
+            getNrfutilLogger()?.info(
+                `Successfully installed nrfutil ${module} version: ${version}`
             );
+        } catch (error) {
+            const errorMessage = `Error while installing nrfutil ${module} version ${version}: ${describeError(
+                error
+            )}`;
+
+            getNrfutilLogger()?.error(errorMessage);
+            throw new Error(errorMessage);
         }
     };
 
@@ -765,22 +818,20 @@ export default async (
     baseDir: string,
     module: string,
     version?: string,
+    coreVersion?: string,
     onProgress?: (progress: Progress, task?: Task) => void
 ) => {
     const sandbox = new NrfutilSandbox(
         baseDir,
         module,
-        versionToInstall(module, version)
+        versionToInstall(module, version),
+        coreVersionsToInstall(coreVersion)
     );
 
     onProgress?.(convertNrfutilProgress({ progressPercentage: 0 }));
-    const result = await sandbox.isSandboxInstalled();
 
-    if (!result) {
+    if (!(await sandbox.isSandboxInstalled())) {
         await sandbox.prepareSandbox(onProgress);
-    } else {
-        // update nrfutil core
-        await sandbox.updateNrfUtilCore(onProgress);
     }
 
     onProgress?.(convertNrfutilProgress({ progressPercentage: 100 }));

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nordicsemiconductor/pc-nrfconnect-shared",
-    "version": "211.0.0",
+    "version": "212.0.0",
     "description": "Shared commodities for developing pc-nrfconnect-* packages",
     "repository": {
         "type": "git",

scripts/nordic-publish.ts

@@ -466,6 +466,7 @@ const getUpdatedAppInfo = async (app: App): Promise<AppInfo> => {
     } = app.packageJson;
 
     const nrfutilModules = nrfConnectForDesktop?.nrfutil;
+    const nrfutilCore = nrfConnectForDesktop?.nrfutilCore;
 
     return {
         name,
@@ -482,6 +483,7 @@ const getUpdatedAppInfo = async (app: App): Promise<AppInfo> => {
                 publishTimestamp: new Date().toISOString(),
                 shasum: app.shasum,
                 nrfutilModules,
+                nrfutilCore,
             },
         },
     };