Add commands for exporting and importing app/fleet releases.

Change-type: minor
Signed-off-by: Carlo Miguel F. Cruz <carloc@balena.io>

completion/_balena

@@ -22,7 +22,7 @@ _balena() {
   key_cmds=( add rm )
   local_cmds=( configure flash )
   os_cmds=( build-config configure download initialize versions )
-  release_cmds=( finalize invalidate validate )
+  release_cmds=( export finalize import invalidate validate )
   tag_cmds=( rm set )
 
 

completion/balena-completion.bash

@@ -21,7 +21,7 @@ _balena_complete()
   key_cmds="add rm"
   local_cmds="configure flash"
   os_cmds="build-config configure download initialize versions"
-  release_cmds="finalize invalidate validate"
+  release_cmds="export finalize import invalidate validate"
   tag_cmds="rm set"
 
 

docs/balena-cli.md

@@ -282,7 +282,9 @@ are encouraged to regularly update the balena CLI to the latest version.
 
 - Releases
 
+	- [release export <commitorid>](#release-export-commitorid)
 	- [release finalize <commitorid>](#release-finalize-commitorid)
+	- [release import <file> <fleet>](#release-import-file-fleet)
 	- [release <commitorid>](#release-commitorid)
 	- [release invalidate <commitorid>](#release-invalidate-commitorid)
 	- [release validate <commitorid>](#release-validate-commitorid)
@@ -3345,6 +3347,37 @@ The notes for this release
 
 # Releases
 
+## release export <commitOrId>
+
+Exporting a release to a file allows you to import an exact 
+copy of the original release into another app.
+
+If the SemVer of a release is provided using the --version option,
+the first argument is assumed to be the fleet's slug.
+
+Only successful releases can be exported.
+
+Examples:
+
+	$ balena release export a777f7345fe3d655c1c981aa642e5555 -o ../path/to/release.tar
+	$ balena release export myOrg/myFleet --version 1.2.3 -o ../path/to/release.tar
+
+### Arguments
+
+#### COMMITORID
+
+commit, ID, or version of the release to export
+
+### Options
+
+#### -o, --output OUTPUT
+
+output path
+
+#### --version VERSION
+
+version of the release to export from the specified fleet
+
 ## release finalize <commitOrId>
 
 Finalize a release. Releases can be "draft" or "final", and this command
@@ -3371,6 +3404,40 @@ the commit or ID of the release to finalize
 
 ### Options
 
+## release import <file> <fleet>
+
+is automatically omitted when importing a release. The backend will auto-increment
+the revision field of the imported release if a release exists with the same semver.
+A release will not be imported if a successful release with the same commit already
+exists.
+
+To export a release to a file, use 'balena release export'.
+
+Use the --override-version option to specify the version 
+of the imported release, overriding the one saved in the file.
+
+Examples:
+
+	$ balena release import ../path/to/release.tar myFleet
+	$ balena release import ../path/to/release.tar myOrg/myFleet
+	$ balena release import ../path/to/release.tar myOrg/myFleet --override-version 1.2.3
+
+### Arguments
+
+#### BUNDLE
+
+path to a file, e.g. "./release.tar"
+
+#### FLEET
+
+fleet that the release will be imported to, e.g. "myOrg/myFleet"
+
+### Options
+
+#### --override-version OVERRIDE-VERSION
+
+Imports this release with the specified version overriding the version in the file.
+
 ## release <commitOrId>
 
 The --json option is recommended when scripting the output of this command,

npm-shrinkwrap.json

@@ -14,6 +14,7 @@
         "@balena/dockerignore": "^1.0.2",
         "@balena/env-parsing": "^1.1.8",
         "@balena/es-version": "^1.0.1",
+        "@balena/release-bundle": "^0.5.2",
         "@oclif/core": "^4.0.8",
         "@sentry/node": "^6.16.1",
         "balena-config-json": "^4.2.0",
@@ -1651,6 +1652,40 @@
         "web-streams-polyfill": "^3.1.0"
       }
     },
+    "node_modules/@balena/release-bundle": {
+      "version": "0.5.2",
+      "resolved": "https://registry.npmjs.org/@balena/release-bundle/-/release-bundle-0.5.2.tgz",
+      "integrity": "sha512-q2ji3Pky9RGeztApTBaoZEF2R8FSiHsFutIvvlmA0ggJKgATxNNavZd4ueYtlK/Nl53g9vUrKmiwzCVgw9rDRw==",
+      "dependencies": {
+        "@balena/resource-bundle": "^0.8.3",
+        "balena-semver": "^2.3.5"
+      },
+      "peerDependencies": {
+        "balena-sdk": "^19.0.0"
+      }
+    },
+    "node_modules/@balena/resource-bundle": {
+      "version": "0.8.3",
+      "resolved": "https://registry.npmjs.org/@balena/resource-bundle/-/resource-bundle-0.8.3.tgz",
+      "integrity": "sha512-WKkeZkZIcrey1l08G1gS60EQCYtTZsOwwmnRhvmjnmWmUAcqa3Z9WqYDqM7ePbFO/pdo9Cd0JK0Xr+pgj3A8ng==",
+      "dependencies": {
+        "auth-header": "^1.0.0",
+        "tar-stream": "^3.1.7"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/@balena/resource-bundle/node_modules/tar-stream": {
+      "version": "3.1.7",
+      "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-3.1.7.tgz",
+      "integrity": "sha512-qJj60CXt7IU1Ffyc3NJMjh6EkuCFej46zUqJ4J7pqYlThyd9bO0XBTmcOIhSzZJVWfsLks0+nle/j538YAW9RQ==",
+      "dependencies": {
+        "b4a": "^1.6.4",
+        "fast-fifo": "^1.2.0",
+        "streamx": "^2.15.0"
+      }
+    },
     "node_modules/@balena/udif": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/@balena/udif/-/udif-1.1.2.tgz",
@@ -5305,6 +5340,11 @@
         "node": ">= 4.0.0"
       }
     },
+    "node_modules/auth-header": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/auth-header/-/auth-header-1.0.0.tgz",
+      "integrity": "sha512-CPPazq09YVDUNNVWo4oSPTQmtwIzHusZhQmahCKvIsk0/xH6U3QsMAv3sM+7+Q0B1K2KJ/Q38OND317uXs4NHA=="
+    },
     "node_modules/available-typed-arrays": {
       "version": "1.0.5",
       "resolved": "https://registry.npmjs.org/available-typed-arrays/-/available-typed-arrays-1.0.5.tgz",

package.json

@@ -195,6 +195,7 @@
     "@balena/dockerignore": "^1.0.2",
     "@balena/env-parsing": "^1.1.8",
     "@balena/es-version": "^1.0.1",
+    "@balena/release-bundle": "^0.5.2",
     "@oclif/core": "^4.0.8",
     "@sentry/node": "^6.16.1",
     "balena-config-json": "^4.2.0",

src/commands/release/export.ts

@@ -0,0 +1,113 @@
+/**
+ * @license
+ * Copyright 2016-2024 Balena Ltd.
+ *
+ * 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 { commitOrIdArg } from '.';
+import { Flags } from '@oclif/core';
+import Command from '../../command';
+import * as cf from '../../utils/common-flags';
+import { getBalenaSdk, stripIndent } from '../../utils/lazy';
+import { create } from '@balena/release-bundle';
+import * as fs from 'fs/promises';
+import * as semver from 'balena-semver';
+import { ExpectedError } from '../../errors';
+
+export default class ReleaseExportCmd extends Command {
+	public static description = stripIndent`
+		Exports a release into a file.
+
+        Exporting a release to a file allows you to import an exact 
+		copy of the original release into another app.
+
+		If the SemVer of a release is provided using the --version option,
+		the first argument is assumed to be the fleet's slug.
+
+		Only successful releases can be exported.
+`;
+	public static examples = [
+		'$ balena release export a777f7345fe3d655c1c981aa642e5555 -o ../path/to/release.tar',
+		'$ balena release export myOrg/myFleet --version 1.2.3 -o ../path/to/release.tar',
+	];
+
+	public static usage = 'release export <commitOrId>';
+
+	public static flags = {
+		output: Flags.string({
+			description: 'output path',
+			char: 'o',
+			required: true,
+		}),
+		version: Flags.string({
+			description: 'version of the release to export from the specified fleet',
+		}),
+		help: cf.help,
+	};
+
+	public static args = {
+		commitOrId: commitOrIdArg({
+			description: 'commit, ID, or version of the release to export',
+			required: true,
+		}),
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params, flags: options } = await this.parse(ReleaseExportCmd);
+
+		const balena = getBalenaSdk();
+
+		let versionInfo = '';
+		try {
+			let releaseDetails:
+				| string
+				| number
+				| { application: string | number; rawVersion: string }; // ReleaseRawVersionApplicationPair
+			if (typeof options.version === 'string') {
+				versionInfo = ` version ${options.version}`;
+				const application = params.commitOrId;
+				const parsedVersion = semver.parse(options.version);
+				if (parsedVersion == null) {
+					throw new ExpectedError(`version must be valid SemVer`);
+				} else {
+					const rawVersion =
+						parsedVersion.build.length === 0
+							? parsedVersion.version
+							: `${parsedVersion.version}+${parsedVersion.build[0]}`;
+					releaseDetails = { application, rawVersion };
+				}
+			} else {
+				releaseDetails = params.commitOrId;
+			}
+
+			const release = await balena.models.release.get(releaseDetails, {
+				$select: ['id'],
+			});
+			const releaseBundle = await create({
+				sdk: balena,
+				releaseId: release.id,
+			});
+			await fs.writeFile(options.output, releaseBundle);
+			console.log(
+				`Release ${params.commitOrId}${versionInfo} has been exported to ${options.output}.`,
+			);
+		} catch (error) {
+			throw new ExpectedError(
+				`Release ${params.commitOrId}${versionInfo} could not be exported: ${error.message}`,
+			);
+		}
+	}
+}

src/commands/release/import.ts

@@ -0,0 +1,108 @@
+/**
+ * @license
+ * Copyright 2016-2024 Balena Ltd.
+ *
+ * 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 { Flags, Args } from '@oclif/core';
+import Command from '../../command';
+import * as cf from '../../utils/common-flags';
+import { getBalenaSdk, stripIndent } from '../../utils/lazy';
+import { apply } from '@balena/release-bundle';
+import type { ReadStream } from 'fs';
+import { promises as fs } from 'fs';
+import { ExpectedError } from '../../errors';
+
+export default class ReleaseImportCmd extends Command {
+	public static description = stripIndent`
+		Imports a release from a file to an app or fleet. The revision field of the release
+		is automatically omitted when importing a release. The backend will auto-increment
+		the revision field of the imported release if a release exists with the same semver.
+		A release will not be imported if a successful release with the same commit already
+		exists.
+
+		To export a release to a file, use 'balena release export'.
+
+		Use the --override-version option to specify the version 
+		of the imported release, overriding the one saved in the file.
+`;
+	public static examples = [
+		'$ balena release import ../path/to/release.tar myFleet',
+		'$ balena release import ../path/to/release.tar myOrg/myFleet',
+		'$ balena release import ../path/to/release.tar myOrg/myFleet --override-version 1.2.3',
+	];
+
+	public static usage = 'release import <file> <fleet>';
+
+	public static flags = {
+		'override-version': Flags.string({
+			description:
+				'Imports this release with the specified version overriding the version in the file.',
+			required: false,
+		}),
+		help: cf.help,
+	};
+
+	public static args = {
+		bundle: Args.string({
+			required: true,
+			description: 'path to a file, e.g. "./release.tar"',
+		}),
+		fleet: Args.string({
+			required: true,
+			description:
+				'fleet that the release will be imported to, e.g. "myOrg/myFleet"',
+		}),
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params, flags: options } = await this.parse(ReleaseImportCmd);
+
+		const balena = getBalenaSdk();
+
+		let bundle: ReadStream;
+		try {
+			try {
+				const fileHandle = await fs.open(params.bundle);
+				bundle = fileHandle.createReadStream();
+			} catch (error) {
+				throw new ExpectedError(
+					`${params.bundle} does not exist or is not accessible`,
+				);
+			}
+
+			const application = await balena.models.application.get(params.fleet, {
+				$select: ['id'],
+			});
+			if (application == null) {
+				throw new ExpectedError(`Fleet ${params.fleet} not found`);
+			}
+			await apply({
+				sdk: balena,
+				application: application.id,
+				stream: bundle,
+				version: options['override-version'],
+			});
+			console.log(
+				`Release bundle ${params.bundle} has been imported to ${params.fleet}.`,
+			);
+		} catch (error) {
+			throw new ExpectedError(
+				`Could not import release bundle ${params.bundle} to ${params.fleet}: ${error.message}`,
+			);
+		}
+	}
+}

tests/test-data/pkg/expected-warnings-darwin-arm64.txt

@@ -205,6 +205,12 @@
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/push/index.js
+> Warning Entry 'main' not found in %1
+  %1: node_modules/@oclif/core/package.json
+  %2: build/commands/release/export.js
+> Warning Entry 'main' not found in %1
+  %1: node_modules/@oclif/core/package.json
+  %2: build/commands/release/import.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/release/index.js

tests/test-data/pkg/expected-warnings-darwin-x64.txt

@@ -205,6 +205,12 @@
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/push/index.js
+> Warning Entry 'main' not found in %1
+  %1: node_modules/@oclif/core/package.json
+  %2: build/commands/release/export.js
+> Warning Entry 'main' not found in %1
+  %1: node_modules/@oclif/core/package.json
+  %2: build/commands/release/import.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/release/index.js

tests/test-data/pkg/expected-warnings-linux-arm64.txt

@@ -205,6 +205,12 @@
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/push/index.js
+> Warning Entry 'main' not found in %1
+  %1: node_modules/@oclif/core/package.json
+  %2: build/commands/release/export.js
+> Warning Entry 'main' not found in %1
+  %1: node_modules/@oclif/core/package.json
+  %2: build/commands/release/import.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/release/index.js

tests/test-data/pkg/expected-warnings-linux-x64.txt

@@ -205,6 +205,12 @@
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/push/index.js
+> Warning Entry 'main' not found in %1
+  %1: node_modules/@oclif/core/package.json
+  %2: build/commands/release/export.js
+> Warning Entry 'main' not found in %1
+  %1: node_modules/@oclif/core/package.json
+  %2: build/commands/release/import.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/release/index.js

tests/test-data/pkg/expected-warnings-win32-x64.txt

@@ -205,6 +205,12 @@
 > Warning Entry 'main' not found in %1
   %1: node_modules\@oclif\core\package.json
   %2: build\commands\push\index.js
+> Warning Entry 'main' not found in %1
+  %1: node_modules\@oclif\core\package.json
+  %2: build\commands\release\export.js
+> Warning Entry 'main' not found in %1
+  %1: node_modules\@oclif\core\package.json
+  %2: build\commands\release\import.js
 > Warning Entry 'main' not found in %1
   %1: node_modules\@oclif\core\package.json
   %2: build\commands\release\index.js