@onekeyfe/hardware-cli 1.2.0-alpha.1 → 1.2.0-alpha.100

package/dist/transports/nobleBlePlugin.js

@@ -0,0 +1,371 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNobleBlePlugin = void 0;
+const hd_shared_1 = require("@onekeyfe/hd-shared");
+const ONEKEY_SERVICE_UUIDS = [hd_shared_1.ONEKEY_SERVICE_UUID];
+const ONEKEY_SERVICE_UUID_ALIASES = (0, hd_shared_1.createKnownBleUuidAliases)(hd_shared_1.ONEKEY_SERVICE_UUID);
+const ONEKEY_WRITE_UUID_ALIASES = (0, hd_shared_1.createKnownBleUuidAliases)(hd_shared_1.ONEKEY_WRITE_CHARACTERISTIC_UUID);
+const ONEKEY_NOTIFY_UUID_ALIASES = (0, hd_shared_1.createKnownBleUuidAliases)(hd_shared_1.ONEKEY_NOTIFY_CHARACTERISTIC_UUID);
+const BLUETOOTH_INIT_TIMEOUT = 10000;
+const DEVICE_SCAN_TIMEOUT = 8000;
+const CONNECTION_TIMEOUT = 8000;
+const SERVICE_DISCOVERY_TIMEOUT = 10000;
+const BLE_CLEANUP_TIMEOUT = 100;
+const BLE_PACKET_SIZE = 192;
+const BLE_ENCRYPTION_ERROR_PATTERNS = [/encryption is insufficient/i, /insufficient encryption/i];
+let noble = null;
+let nobleReadyPromise = null;
+const discoveredDevices = new Map();
+const connectedDevices = new Map();
+const deviceCharacteristics = new Map();
+const notificationStates = new Map();
+const notificationGenerations = new Map();
+function isOneKeyPeripheral(peripheral) {
+    const serviceUuids = peripheral.advertisement?.serviceUuids;
+    return ((0, hd_shared_1.hasOnekeyCommunicationService)(serviceUuids) &&
+        (0, hd_shared_1.isOnekeyBluetoothDevice)({
+            id: peripheral.id,
+            localName: peripheral.advertisement?.localName,
+            serviceUuids,
+        }));
+}
+function enqueueNotification(deviceId, generation, data) {
+    const state = notificationStates.get(deviceId);
+    if (!state || state.generation !== generation)
+        return;
+    const hex = data.toString('hex');
+    const [receiver] = state.pendingReceivers;
+    if (receiver) {
+        state.pendingReceivers.delete(receiver);
+        receiver.resolve(hex);
+        return;
+    }
+    state.queue.push(hex);
+}
+function createNotificationState(deviceId) {
+    const existing = notificationStates.get(deviceId);
+    if (existing) {
+        const error = new Error(`BLE notification state replaced for ${deviceId}`);
+        existing.pendingReceivers.forEach(receiver => receiver.reject(error));
+    }
+    const generation = (notificationGenerations.get(deviceId) ?? 0) + 1;
+    notificationGenerations.set(deviceId, generation);
+    const state = {
+        generation,
+        queue: [],
+        pendingReceivers: new Set(),
+    };
+    notificationStates.set(deviceId, state);
+    return state;
+}
+function clearNotificationState(deviceId, reason) {
+    const state = notificationStates.get(deviceId);
+    if (!state)
+        return;
+    notificationStates.delete(deviceId);
+    const error = new Error(reason);
+    state.pendingReceivers.forEach(receiver => receiver.reject(error));
+    state.pendingReceivers.clear();
+    state.queue.length = 0;
+}
+function waitForNobleCleanup(registerCallback) {
+    return new Promise(resolve => {
+        let completed = false;
+        const complete = () => {
+            if (completed)
+                return;
+            completed = true;
+            clearTimeout(timeout);
+            resolve();
+        };
+        const timeout = setTimeout(complete, BLE_CLEANUP_TIMEOUT);
+        try {
+            registerCallback(complete);
+        }
+        catch {
+            complete();
+        }
+    });
+}
+async function initializeNoble() {
+    if (!noble) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
+            noble = require('@stoprocent/noble');
+        }
+        catch (error) {
+            throw hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleUnsupported, error instanceof Error ? error.message : String(error));
+        }
+    }
+    if (noble.state === 'poweredOn')
+        return;
+    if (nobleReadyPromise) {
+        await nobleReadyPromise;
+        return;
+    }
+    nobleReadyPromise = new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            noble?.removeListener('stateChange', onStateChange);
+            reject(hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BlePoweredOff, 'Bluetooth is not powered on'));
+        }, BLUETOOTH_INIT_TIMEOUT);
+        const onStateChange = (state) => {
+            if (state === 'poweredOn') {
+                clearTimeout(timeout);
+                noble?.removeListener('stateChange', onStateChange);
+                resolve();
+            }
+            else if (state === 'unsupported') {
+                clearTimeout(timeout);
+                noble?.removeListener('stateChange', onStateChange);
+                reject(hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleUnsupported));
+            }
+        };
+        noble?.on('stateChange', onStateChange);
+    }).finally(() => {
+        nobleReadyPromise = null;
+    });
+    await nobleReadyPromise;
+}
+function stopScanning() {
+    try {
+        noble?.stopScanning();
+    }
+    catch {
+        // ignore best-effort scan cleanup
+    }
+}
+async function scanDevices(targetDeviceId) {
+    await initializeNoble();
+    if (!noble) {
+        throw hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.RuntimeError, 'Noble not initialized');
+    }
+    if (!targetDeviceId) {
+        discoveredDevices.clear();
+    }
+    const nobleInstance = noble;
+    return new Promise((resolve, reject) => {
+        const found = new Map();
+        const cleanup = () => {
+            clearTimeout(timeout);
+            nobleInstance.removeListener('discover', onDiscover);
+            stopScanning();
+        };
+        const finish = () => {
+            cleanup();
+            resolve([...found.values()]);
+        };
+        const onDiscover = (peripheral) => {
+            if (targetDeviceId && peripheral.id !== targetDeviceId)
+                return;
+            if (!isOneKeyPeripheral(peripheral))
+                return;
+            discoveredDevices.set(peripheral.id, peripheral);
+            found.set(peripheral.id, peripheral);
+            if (targetDeviceId) {
+                finish();
+            }
+        };
+        const timeout = setTimeout(finish, DEVICE_SCAN_TIMEOUT);
+        nobleInstance.on('discover', onDiscover);
+        nobleInstance.startScanning([], false, (error) => {
+            if (error) {
+                cleanup();
+                reject(hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleScanError, error.message));
+            }
+        });
+    });
+}
+function connectPeripheral(peripheral) {
+    if (peripheral.state === 'connected')
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            reject(hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleConnectedError, 'Connection timeout'));
+        }, CONNECTION_TIMEOUT);
+        peripheral.connect((error) => {
+            clearTimeout(timeout);
+            if (error) {
+                reject(hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleConnectedError, error.message));
+                return;
+            }
+            resolve();
+        });
+    });
+}
+async function discoverCharacteristics(peripheral) {
+    const services = await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            reject(hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleServiceNotFound, 'Service discovery timeout'));
+        }, SERVICE_DISCOVERY_TIMEOUT);
+        peripheral.discoverServices([], (error, discoveredServices) => {
+            clearTimeout(timeout);
+            if (error) {
+                reject(hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleServiceNotFound, error.message));
+                return;
+            }
+            resolve(discoveredServices);
+        });
+    });
+    const service = services.find(s => (0, hd_shared_1.matchesKnownBleUuid)(s.uuid, ONEKEY_SERVICE_UUID_ALIASES));
+    if (!service) {
+        throw hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleServiceNotFound, 'No BLE service found');
+    }
+    const selectedService = service;
+    const characteristics = await new Promise((resolve, reject) => {
+        selectedService.discoverCharacteristics([], (error, discoveredCharacteristics) => {
+            if (error) {
+                reject(hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleCharacteristicNotFound, error.message));
+                return;
+            }
+            resolve(discoveredCharacteristics);
+        });
+    });
+    let writeCharacteristic;
+    let notifyCharacteristic;
+    for (const characteristic of characteristics) {
+        if ((0, hd_shared_1.matchesKnownBleUuid)(characteristic.uuid, ONEKEY_WRITE_UUID_ALIASES)) {
+            writeCharacteristic = characteristic;
+        }
+        else if ((0, hd_shared_1.matchesKnownBleUuid)(characteristic.uuid, ONEKEY_NOTIFY_UUID_ALIASES)) {
+            notifyCharacteristic = characteristic;
+        }
+    }
+    if (!writeCharacteristic || !notifyCharacteristic) {
+        throw hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleCharacteristicNotFound, 'Required OneKey BLE characteristics not found');
+    }
+    return {
+        write: writeCharacteristic,
+        notify: notifyCharacteristic,
+    };
+}
+function subscribeNotifications(deviceId, generation, notifyCharacteristic) {
+    return waitForNobleCleanup(callback => notifyCharacteristic.unsubscribe(callback))
+        .then(() => new Promise((resolve, reject) => {
+        notifyCharacteristic.subscribe((error) => {
+            if (error) {
+                const errorMessage = error.message || String(error);
+                if (BLE_ENCRYPTION_ERROR_PATTERNS.some(pattern => pattern.test(errorMessage))) {
+                    reject(hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleDeviceNotBonded, `BLE device ${deviceId} is not paired or the encrypted link is not ready: ${errorMessage}`));
+                    return;
+                }
+                reject(hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleCharacteristicNotifyChangeFailure, `Failed to subscribe notifications for ${deviceId}: ${errorMessage}`));
+                return;
+            }
+            resolve();
+        });
+    }))
+        .then(() => {
+        notifyCharacteristic.removeAllListeners('data');
+        notifyCharacteristic.on('data', data => enqueueNotification(deviceId, generation, data));
+    })
+        .catch(error => {
+        notifyCharacteristic.removeAllListeners('data');
+        if (error) {
+            throw error;
+        }
+        throw hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleCharacteristicNotifyChangeFailure);
+    });
+}
+function writeCharacteristic(characteristic, buffer, withoutResponse) {
+    return new Promise((resolve, reject) => {
+        characteristic.write(buffer, withoutResponse, (error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+    });
+}
+async function disconnectDevice(uuid) {
+    const peripheral = connectedDevices.get(uuid);
+    const characteristics = deviceCharacteristics.get(uuid);
+    clearNotificationState(uuid, `BLE device disconnected: ${uuid}`);
+    if (characteristics) {
+        characteristics.notify.removeAllListeners('data');
+        await waitForNobleCleanup(callback => characteristics.notify.unsubscribe(callback));
+    }
+    connectedDevices.delete(uuid);
+    deviceCharacteristics.delete(uuid);
+    if (!peripheral || peripheral.state === 'disconnected')
+        return;
+    await waitForNobleCleanup(callback => peripheral.disconnect(callback));
+}
+function createNobleBlePlugin() {
+    return {
+        version: 'OneKey-CLI-Noble-1.0',
+        async init() {
+            await initializeNoble();
+        },
+        async enumerate() {
+            const devices = await scanDevices();
+            return devices.map(device => ({
+                commType: 'ble',
+                id: device.id,
+                name: device.advertisement?.localName || 'Unknown BLE Device',
+            }));
+        },
+        async connect(uuid) {
+            let peripheral = discoveredDevices.get(uuid);
+            if (!peripheral) {
+                [peripheral] = await scanDevices(uuid);
+            }
+            if (!peripheral) {
+                throw hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.DeviceNotFound, `BLE device not found: ${uuid}`);
+            }
+            await connectPeripheral(peripheral);
+            let characteristics;
+            try {
+                characteristics = await discoverCharacteristics(peripheral);
+                const notificationState = createNotificationState(uuid);
+                await subscribeNotifications(uuid, notificationState.generation, characteristics.notify);
+                connectedDevices.set(uuid, peripheral);
+                deviceCharacteristics.set(uuid, characteristics);
+            }
+            catch (error) {
+                clearNotificationState(uuid, `BLE notification subscription failed: ${uuid}`);
+                if (characteristics) {
+                    characteristics.notify.removeAllListeners('data');
+                    await waitForNobleCleanup(callback => characteristics?.notify.unsubscribe(callback));
+                }
+                if (peripheral.state !== 'disconnected') {
+                    await waitForNobleCleanup(callback => peripheral?.disconnect(callback));
+                }
+                throw error;
+            }
+        },
+        async disconnect(uuid) {
+            await disconnectDevice(uuid);
+        },
+        async send(uuid, data, options) {
+            const characteristics = deviceCharacteristics.get(uuid);
+            if (!characteristics) {
+                throw hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.BleCharacteristicNotFound, `BLE device is not connected: ${uuid}`);
+            }
+            const buffer = Buffer.from(data, 'hex');
+            const withoutResponse = options?.withoutResponse ?? true;
+            for (let offset = 0; offset < buffer.length; offset += BLE_PACKET_SIZE) {
+                const chunk = buffer.subarray(offset, Math.min(offset + BLE_PACKET_SIZE, buffer.length));
+                await writeCharacteristic(characteristics.write, chunk, withoutResponse);
+            }
+        },
+        async receive(uuid) {
+            const resolvedUuid = uuid ??
+                (notificationStates.size === 1 ? notificationStates.keys().next().value : undefined);
+            if (!resolvedUuid) {
+                throw hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.RuntimeError, 'BLE receive requires a device UUID when multiple devices are connected');
+            }
+            const state = notificationStates.get(resolvedUuid);
+            if (!state) {
+                throw hd_shared_1.ERRORS.TypedError(hd_shared_1.HardwareErrorCode.TransportNotFound, `BLE notification state not found: ${resolvedUuid}`);
+            }
+            const queued = state.queue.shift();
+            if (queued !== undefined)
+                return queued;
+            return new Promise((resolve, reject) => {
+                state.pendingReceivers.add({ resolve, reject });
+            });
+        },
+    };
+}
+exports.createNobleBlePlugin = createNobleBlePlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onekeyfe/hardware-cli",
-  "version": "1.2.0-alpha.1",
+  "version": "1.2.0-alpha.100",
   "description": "OneKey hardware wallet CLI for testing device communication",
   "author": "OneKey",
   "license": "Apache-2.0",
@@ -23,6 +23,7 @@
     "start": "node dist/cli.js",
     "search": "node dist/cli.js search",
     "get-features": "node dist/cli.js get-features",
+    "get-state": "node dist/cli.js get-state",
     "get-address": "node dist/cli.js get-address",
     "ping": "node dist/cli.js ping",
     "lint": "eslint .",
@@ -30,11 +31,12 @@
     "test": "jest"
   },
   "dependencies": {
-    "@onekeyfe/hd-common-connect-sdk": "1.2.0-alpha.1",
-    "@onekeyfe/hd-core": "1.2.0-alpha.1",
-    "@onekeyfe/hd-shared": "1.2.0-alpha.1",
-    "@onekeyfe/hd-transport-usb": "1.2.0-alpha.1",
+    "@onekeyfe/hd-common-connect-sdk": "1.2.0-alpha.100",
+    "@onekeyfe/hd-core": "1.2.0-alpha.100",
+    "@onekeyfe/hd-shared": "1.2.0-alpha.100",
+    "@onekeyfe/hd-transport-usb": "1.2.0-alpha.100",
+    "@stoprocent/noble": "2.3.16",
     "commander": "^12.0.0"
   },
-  "gitHead": "4f4aae3a47be7bd54b4db4a10c400056784e01bd"
+  "gitHead": "4e70f0a01da0c3c2dab687b8c4bf4f18cf4ad0c0"
 }

package/src/__tests__/cli-version.test.ts

@@ -0,0 +1,8 @@
+import packageJson from '../../package.json';
+import { program } from '../cli';
+
+describe('CLI 版本', () => {
+  test('与发布包 package.json 使用同一个版本来源', () => {
+    expect(program.version()).toBe(packageJson.version);
+  });
+});

package/src/__tests__/device-selection.test.ts

@@ -0,0 +1,29 @@
+import { selectSearchDevice } from '../deviceSelection';
+
+describe('selectSearchDevice', () => {
+  it('多设备环境优先选择显式 connectId 对应的设备', () => {
+    const devices = [
+      { connectId: 'first-device', name: 'Pro A9CA' },
+      { connectId: 'target-device', name: 'Pro2 6136' },
+    ];
+
+    expect(selectSearchDevice(devices, 'target-device')).toEqual(devices[1]);
+  });
+
+  it('未指定 connectId 时保持选择第一台设备的兼容行为', () => {
+    const devices = [
+      { connectId: 'first-device', name: 'Pro2 6136' },
+      { connectId: 'second-device', name: 'Pro2 C445' },
+    ];
+
+    expect(selectSearchDevice(devices)).toEqual(devices[0]);
+  });
+
+  it('显式 connectId 暂未出现在扫描结果时仍保留该目标', () => {
+    const devices = [{ connectId: 'other-device', name: 'Pro2 C445' }];
+
+    expect(selectSearchDevice(devices, 'target-device')).toEqual({
+      connectId: 'target-device',
+    });
+  });
+});

package/src/__tests__/device-state-commands.test.ts

@@ -0,0 +1,118 @@
+import { getCanonicalDeviceState, getCompatibleFeatures } from '../deviceStateCommands';
+
+const createSdkMock = () => ({
+  searchDevices: jest.fn(),
+  getDeviceState: jest.fn(),
+  getFeatures: jest.fn(),
+});
+
+describe('设备状态 CLI 兼容层', () => {
+  test('Protocol V2 直接返回 SDK 搜索结果中的兼容 features', async () => {
+    const sdk = createSdkMock();
+    const features = {
+      protocol: 'V2',
+      deviceType: 'pro2',
+      deviceId: 'device-id',
+    };
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [
+        {
+          connectId: 'pro2-connect-id',
+          state: { protocol: 'V2' },
+          features,
+        },
+      ],
+    });
+
+    await expect(getCompatibleFeatures(sdk as never, 'pro2-connect-id')).resolves.toEqual({
+      success: true,
+      payload: features,
+    });
+    expect(sdk.getFeatures).not.toHaveBeenCalled();
+  });
+
+  test('Protocol V1 继续调用公共 getFeatures 保持旧行为', async () => {
+    const sdk = createSdkMock();
+    const response = {
+      success: true,
+      payload: { protocol: 'V1', label: 'Classic' },
+    };
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [
+        {
+          connectId: 'classic-connect-id',
+          state: { protocol: 'V1' },
+        },
+      ],
+    });
+    sdk.getFeatures.mockResolvedValue(response);
+
+    await expect(getCompatibleFeatures(sdk as never, 'classic-connect-id')).resolves.toBe(response);
+    expect(sdk.getFeatures).toHaveBeenCalledWith('classic-connect-id');
+  });
+
+  test('未显式指定设备时选择搜索结果中的第一台设备', async () => {
+    const sdk = createSdkMock();
+    const response = { success: true, payload: { protocol: 'V1' } };
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [{ connectId: 'first-device', state: { protocol: 'V1' } }],
+    });
+    sdk.getFeatures.mockResolvedValue(response);
+
+    await expect(getCompatibleFeatures(sdk as never)).resolves.toBe(response);
+    expect(sdk.getFeatures).toHaveBeenCalledWith('first-device');
+  });
+
+  test('显式 connectId 不在搜索结果时返回结构化错误', async () => {
+    const sdk = createSdkMock();
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [{ connectId: 'another-device', state: { protocol: 'V1' } }],
+    });
+
+    await expect(getCompatibleFeatures(sdk as never, 'missing-device')).resolves.toEqual({
+      success: false,
+      payload: {
+        code: 'DEVICE_NOT_FOUND',
+        error: 'Device not found: missing-device',
+      },
+    });
+    expect(sdk.getFeatures).not.toHaveBeenCalled();
+  });
+
+  test('get-state 将 firmware scope 传给 SDK', async () => {
+    const sdk = createSdkMock();
+    const response = { success: true, payload: { protocol: 'V2' } };
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [{ connectId: 'pro2-connect-id', state: { protocol: 'V2' } }],
+    });
+    sdk.getDeviceState.mockResolvedValue(response);
+
+    await expect(
+      getCanonicalDeviceState(sdk as never, 'pro2-connect-id', 'firmware')
+    ).resolves.toBe(response);
+    expect(sdk.getDeviceState).toHaveBeenCalledWith('pro2-connect-id', {
+      scope: 'firmware',
+    });
+    expect(sdk.searchDevices).toHaveBeenCalledTimes(1);
+  });
+
+  test('get-state 未指定 connectId 时搜索并选择第一台设备', async () => {
+    const sdk = createSdkMock();
+    const state = { protocol: 'V2', revision: 2 };
+    sdk.searchDevices.mockResolvedValue({
+      success: true,
+      payload: [{ connectId: 'pro2-connect-id', state }],
+    });
+
+    await expect(getCanonicalDeviceState(sdk as never, undefined, 'runtime')).resolves.toEqual({
+      success: true,
+      payload: state,
+    });
+    expect(sdk.getDeviceState).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/firmware-update-legacy-command.test.ts

@@ -0,0 +1,18 @@
+import { getLegacyFirmwareConnectTimeout, program } from '../cli';
+
+describe('firmware-update-legacy CLI command', () => {
+  test('提供 Classic/Pure 的本地固件升级命令', () => {
+    const command = program.commands.find(item => item.name() === 'firmware-update-legacy');
+
+    expect(command).toBeDefined();
+    expect(command?.description()).toBe('Update Classic/Pure firmware through the legacy protocol');
+    expect(command?.options.find(option => option.long === '--binary')?.mandatory).toBe(true);
+    expect(command?.options.some(option => option.long === '--device-name')).toBe(true);
+    expect(command?.options.some(option => option.long === '--update-type')).toBe(true);
+  });
+
+  test('USB Classic 固件升级使用足够的设备探测超时', () => {
+    expect(getLegacyFirmwareConnectTimeout('usb')).toBe(90_000);
+    expect(getLegacyFirmwareConnectTimeout('ble')).toBeUndefined();
+  });
+});

package/src/__tests__/firmware-update-v4-command.test.ts

@@ -0,0 +1,101 @@
+import { createSDK, disposeSDK } from '../sdk';
+import { program, runFirmwareUpdateV4WithRetry } from '../cli';
+
+jest.mock('../sdk', () => ({
+  createSDK: jest.fn(),
+  disposeSDK: jest.fn(),
+}));
+
+const transientProbeFailure = {
+  success: false,
+  payload: {
+    error: 'Device protocol mismatch: expected V2; device did not respond to expected protocol',
+  },
+};
+
+const createSdkMock = () => ({
+  getDeviceState: jest.fn(),
+  firmwareUpdateV4: jest.fn(),
+  on: jest.fn(),
+  off: jest.fn(),
+});
+
+describe('firmware-update-v4 CLI command', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test('exposes firmware-update-v4 as the formal command', () => {
+    const command = program.commands.find(item => item.name() === 'firmware-update-v4');
+
+    expect(command).toBeDefined();
+    expect(command?.description()).toBe(
+      'Run Protocol V2 firmware update through sdk.firmwareUpdateV4'
+    );
+    expect(command?.options.some(option => option.long === '--resource-archive')).toBe(true);
+  });
+
+  test('does not expose the pre-release firmware-update-v4-debug command', () => {
+    expect(program.commands.some(item => item.name() === 'firmware-update-v4-debug')).toBe(false);
+    expect(program.commands.some(item => item.aliases().includes('firmware-update-v4-debug'))).toBe(
+      false
+    );
+  });
+
+  test('retries only the read-only USB probe before starting the firmware update', async () => {
+    const firstSdk = createSdkMock();
+    const retrySdk = createSdkMock();
+    firstSdk.getDeviceState.mockResolvedValue(transientProbeFailure);
+    retrySdk.getDeviceState.mockResolvedValue({ success: true, payload: { protocol: 'V2' } });
+    retrySdk.firmwareUpdateV4.mockResolvedValue({ success: true, payload: {} });
+    jest.mocked(createSDK).mockResolvedValue(retrySdk as never);
+    jest.mocked(disposeSDK).mockResolvedValue(undefined);
+    jest.spyOn(global, 'setTimeout').mockImplementation(callback => {
+      callback();
+      return 0 as never;
+    });
+
+    const result = await runFirmwareUpdateV4WithRetry({
+      sdk: firstSdk as never,
+      globalOpts: { transport: 'usb', connectId: 'stale-connect-id' },
+      params: { applicationP1Binary: new ArrayBuffer(1) } as never,
+      retries: 1,
+    });
+
+    expect(firstSdk.firmwareUpdateV4).not.toHaveBeenCalled();
+    expect(disposeSDK).toHaveBeenCalledTimes(1);
+    expect(retrySdk.getDeviceState).toHaveBeenCalledWith(undefined, {
+      scope: 'runtime',
+      connectProtocol: 'V2',
+      retryCount: 0,
+    });
+    expect(retrySdk.firmwareUpdateV4).toHaveBeenCalledTimes(1);
+    expect(result).toMatchObject({ success: true, payload: { metrics: { attempt: 2 } } });
+  });
+
+  test('does not replay firmwareUpdateV4 after the read-only probe succeeds', async () => {
+    const sdk = createSdkMock();
+    sdk.getDeviceState.mockResolvedValue({ success: true, payload: { protocol: 'V2' } });
+    sdk.firmwareUpdateV4.mockResolvedValue(transientProbeFailure);
+
+    const result = await runFirmwareUpdateV4WithRetry({
+      sdk: sdk as never,
+      globalOpts: { transport: 'usb', connectId: 'pro2-connect-id' },
+      params: { applicationP1Binary: new ArrayBuffer(1) } as never,
+      retries: 2,
+    });
+
+    expect(sdk.getDeviceState).toHaveBeenCalledTimes(1);
+    expect(sdk.firmwareUpdateV4).toHaveBeenCalledTimes(1);
+    expect(disposeSDK).not.toHaveBeenCalled();
+    expect(createSDK).not.toHaveBeenCalled();
+    expect(result).toMatchObject({
+      success: false,
+      payload: { error: transientProbeFailure.payload.error, metrics: { attempt: 1 } },
+    });
+  });
+});