Chore/sc 138087/usb env command

package.json

@@ -68,7 +68,7 @@
     "particle-api-js": "^11.1.7",
     "particle-commands": "^1.0.6",
     "particle-library-manager": "^1.0.6",
-    "particle-usb": "^4.0.1",
+    "particle-usb": "^4.1.0",
     "request": "^2.88.2",
     "safe-buffer": "^5.2.0",
     "semver": "^7.5.2",

src/cli/usb.js

@@ -168,6 +168,19 @@ module.exports = ({ commandProcessor, root }) => {
 		}
 	});
 
+	commandProcessor.createCommand(usb, 'env', 'Gets environment variables from a device', {
+		params: '[devices...]',
+		options: commonOptions,
+		examples: {
+			'$0 $command': 'Gets environment variables from the connected device',
+			'$0 $command --all': 'Gets environment variables from all devices connected over USB',
+			'$0 $command my_device': 'Gets environment variables from the device named "my_device"'
+		},
+		handler: (args) => {
+			return usbCommand().getEnv(args);
+		}
+	});
+
 	return usb;
 };
 

src/cli/usb.test.js

@@ -40,6 +40,7 @@ describe('USB Command-Line Interface', () => {
 					'  configure           Update the system USB configuration',
 					'  cloud-status        Check a device\'s cloud connection state',
 					'  network-interfaces  Gets the network configuration of the device',
+					'  env                 Gets environment variables from a device',
 					''
 				].join('\n'));
 			});

src/cmd/usb.js

@@ -1,4 +1,5 @@
 'use strict';
+const os = require('os');
 const { asyncMapSeries, buildDeviceFilter } = require('../lib/utilities');
 const { getDevice, formatDeviceInfo } = require('./device-util');
 const { getUsbDevices, openUsbDevice, TimeoutError, DeviceProtectionError, forEachUsbDevice, executeWithUsbDevice } = require('./usb-util');
@@ -118,6 +119,77 @@ module.exports = class UsbCommand extends CLICommandBase {
 			});
 	}
 
+	getEnv(args) {
+		args.api = this._api;
+		args.auth = this._auth;
+		const output = [];
+
+		return forEachUsbDevice(args, async (usbDevice) => {
+			const result = await usbDevice.getEnv();
+			const platform = platformForId(usbDevice.platformId);
+			const formattedOutput = this._formatEnvOutput(result, platform.displayName, usbDevice.id);
+			output.push(...formattedOutput);
+			return result;
+		}).then(() => {
+			output.forEach(line => console.log(line));
+		});
+	}
+
+	_formatEnvOutput(result, platformName, deviceId) {
+		const output = [];
+		const push = line => output.push(line);
+
+		push('');
+		push(`${chalk.bold('Device:')} ${chalk.cyan(deviceId)} (${chalk.cyan(platformName)})`);
+
+		if (result.snapshot) {
+			push(`${chalk.bold('Snapshot Hash:')} ${chalk.gray(result.snapshot.hash)}`);
+		}
+
+		const envVars = result.env ?? {};
+		const entries = Object.entries(envVars);
+
+		if (entries.length === 0) {
+			push(chalk.yellow('  No environment variables set'));
+			push('');
+			return output;
+		}
+
+		push(chalk.bold(`${os.EOL}Environment Variables:`));
+
+		const { appVars, systemVars } = this._groupEnvVars(entries);
+
+		this._renderEnvGroup(output, '  Firmware:', appVars, 'green');
+		appVars.length > 0 && systemVars.length > 0 && push('');
+		this._renderEnvGroup(output, '  Cloud:', systemVars, 'cyan');
+
+		push('');
+		return output;
+	}
+
+	_groupEnvVars(entries) {
+		return entries.reduce(
+			(acc, [key, { value, isApp }]) => {
+				const target = isApp ? acc.appVars : acc.systemVars;
+				target.push({ key, value });
+				return acc;
+			},
+			{ appVars: [], systemVars: [] }
+		);
+	}
+
+	_renderEnvGroup(output, title, vars, color) {
+		if (vars.length === 0) {
+			return;
+		}
+		output.push(chalk.dim(title));
+		vars.sort((a, b) => a.key.localeCompare(b.key))
+			.forEach(({ key, value }) => {
+				output.push(`    ${chalk[color](key)}=${chalk.white(value)}`);
+			});
+
+	}
+
 	stopListening(args) {
 		args.api = this._api;
 		args.auth = this._auth;

src/cmd/usb.test.js

@@ -1,4 +1,5 @@
 'use strict';
+const os = require('os');
 const { expect } = require('../../test/setup');
 const { default: stripAnsi } = require('strip-ansi');
 const UsbCommands = require('./usb');
@@ -111,4 +112,175 @@ describe('USB Commands', () => {
 			expect(res.map(stripAnsi)).to.eql(expectedOutput);
 		});
 	});
+
+	describe('_formatEnvOutput', () => {
+		let usbCommands;
+
+		beforeEach(() => {
+			usbCommands = new UsbCommands({
+				access_token: '1234',
+				apiUrl: 'https://api.particle.io'
+			});
+		});
+
+		it('formats output with application variables only', () => {
+			const result = {
+				env: {
+					FOO: { value: 'bar', isApp: true },
+					TEST: { value: 'baz', isApp: true }
+				}
+			};
+
+			const output = usbCommands._formatEnvOutput(result, 'P2', '0123456789abcdef');
+			const cleanOutput = output.map(stripAnsi);
+
+			expect(cleanOutput).to.deep.equal([
+				'',
+				'Device: 0123456789abcdef (P2)',
+				`${os.EOL}Environment Variables:`,
+				'  Firmware:',
+				'    FOO=bar',
+				'    TEST=baz',
+				''
+			]);
+		});
+
+		it('formats output with system variables only', () => {
+			const result = {
+				env: {
+					SYS_VAR1: { value: 'value1', isApp: false },
+					SYS_VAR2: { value: 'value2', isApp: false }
+				}
+			};
+
+			const output = usbCommands._formatEnvOutput(result, 'P2', '0123456789abcdef');
+			const cleanOutput = output.map(stripAnsi);
+
+			expect(cleanOutput).to.deep.equal([
+				'',
+				'Device: 0123456789abcdef (P2)',
+				`${os.EOL}Environment Variables:`,
+				'  Cloud:',
+				'    SYS_VAR1=value1',
+				'    SYS_VAR2=value2',
+				''
+			]);
+		});
+
+		it('formats output with both application and system variables', () => {
+			const result = {
+				env: {
+					APP_KEY: { value: 'app_value', isApp: true },
+					SYS_KEY: { value: 'sys_value', isApp: false },
+					ANOTHER_APP: { value: 'another_app', isApp: true }
+				}
+			};
+
+			const output = usbCommands._formatEnvOutput(result, 'Photon', 'abc123def456');
+			const cleanOutput = output.map(stripAnsi);
+
+			expect(cleanOutput).to.deep.equal([
+				'',
+				'Device: abc123def456 (Photon)',
+				`${os.EOL}Environment Variables:`,
+				'  Firmware:',
+				'    ANOTHER_APP=another_app',
+				'    APP_KEY=app_value',
+				'',
+				'  Cloud:',
+				'    SYS_KEY=sys_value',
+				''
+			]);
+		});
+
+		it('formats output when no environment variables are set', () => {
+			const result = {
+				env: {}
+			};
+
+			const output = usbCommands._formatEnvOutput(result, 'Argon', 'device123');
+			const cleanOutput = output.map(stripAnsi);
+
+			expect(cleanOutput).to.deep.equal([
+				'',
+				'Device: device123 (Argon)',
+				'  No environment variables set',
+				''
+			]);
+		});
+
+		it('includes snapshot hash when present', () => {
+			const result = {
+				env: {
+					MY_VAR: { value: 'my_value', isApp: true }
+				},
+				snapshot: {
+					hash: 'abc123def456789'
+				}
+			};
+
+			const output = usbCommands._formatEnvOutput(result, 'P2', '0123456789abcdef');
+			const cleanOutput = output.map(stripAnsi);
+
+			expect(cleanOutput).to.deep.equal([
+				'',
+				'Device: 0123456789abcdef (P2)',
+				'Snapshot Hash: abc123def456789',
+				`${os.EOL}Environment Variables:`,
+				'  Firmware:',
+				'    MY_VAR=my_value',
+				''
+			]);
+		});
+
+		it('sorts variables alphabetically within each category', () => {
+			const result = {
+				env: {
+					ZEBRA: { value: 'z', isApp: true },
+					APPLE: { value: 'a', isApp: true },
+					BANANA: { value: 'b', isApp: true },
+					SYS_Z: { value: 'sz', isApp: false },
+					SYS_A: { value: 'sa', isApp: false }
+				}
+			};
+
+			const output = usbCommands._formatEnvOutput(result, 'P2', 'device123');
+			const cleanOutput = output.map(stripAnsi);
+
+			expect(cleanOutput).to.deep.equal([
+				'',
+				'Device: device123 (P2)',
+				`${os.EOL}Environment Variables:`,
+				'  Firmware:',
+				'    APPLE=a',
+				'    BANANA=b',
+				'    ZEBRA=z',
+				'',
+				'  Cloud:',
+				'    SYS_A=sa',
+				'    SYS_Z=sz',
+				''
+			]);
+		});
+
+		it('handles special characters in values', () => {
+			const result = {
+				env: {
+					SPECIAL: { value: 'value with spaces & symbols!@#$%', isApp: true }
+				}
+			};
+
+			const output = usbCommands._formatEnvOutput(result, 'P2', 'device123');
+			const cleanOutput = output.map(stripAnsi);
+
+			expect(cleanOutput).to.deep.equal([
+				'',
+				'Device: device123 (P2)',
+				`${os.EOL}Environment Variables:`,
+				'  Firmware:',
+				'    SPECIAL=value with spaces & symbols!@#$%',
+				''
+			]);
+		});
+	});
 });

test/e2e/help.e2e.js

@@ -81,7 +81,7 @@ describe('Help & Unknown Command / Argument Handling', () => {
 		'token revoke', 'token create', 'token', 'udp send', 'udp listen', 'udp', 'update',
 		'update-cli', 'usb list', 'usb start-listening', 'usb listen',
 		'usb stop-listening', 'usb safe-mode', 'usb dfu', 'usb reset',
-		'usb setup-done', 'usb configure', 'usb cloud-status', 'usb network-interfaces', 'usb',
+		'usb setup-done', 'usb configure', 'usb cloud-status', 'usb network-interfaces', 'usb env', 'usb',
 		'variable list', 'variable get', 'variable monitor', 'variable',
 		'webhook create', 'webhook list', 'webhook delete', 'webhook POST',
 		'webhook GET', 'webhook', 'whoami', 'wifi add', 'wifi join', 'wifi clear', 'wifi list', 'wifi remove', 'wifi current', 'wifi'