@onekeyfe/hardware-cli 1.1.25-alpha.0 → 1.1.25

package/src/cli.ts

@@ -14,13 +14,12 @@ const program = new Command();
 program
   .name('onekey-hw')
   .description('OneKey hardware wallet CLI for AI agent integration')
-  .version('1.1.25-alpha.0');
+  .version('1.1.25-alpha.1');
 
 // ============================================================
 // Global Options
 // ============================================================
 
-program.option('--json', 'Output in JSON format (for agent consumption)');
 program.option('--connect-id <id>', 'Device connection ID (USB: serial, iOS: uuid, Android: MAC)');
 program.option(
   '--device-id <id>',
@@ -36,25 +35,31 @@ program.option('--use-empty-passphrase', 'Use standard wallet (skip passphrase p
 program
   .command('search')
   .description('Search for connected OneKey hardware wallet devices')
-  .option('--timeout <ms>', 'Search timeout in milliseconds', '10000')
-  .action(async opts => {
-    const sdk = await createSDK(program.opts());
-    try {
-      const result = await sdk.searchDevices();
-      outputResult(program.opts(), result);
-    } finally {
-      sdk.dispose();
-    }
-  });
-
-program
-  .command('status')
-  .description('Get device features and current status')
   .action(async () => {
     const globalOpts = program.opts();
     const sdk = await createSDK(globalOpts);
     try {
-      const result = await sdk.getFeatures(globalOpts.connectId);
+      const result = await sdk.searchDevices();
+
+      // Auto-fetch features for each discovered device (doesn't require PIN)
+      if (result?.success && Array.isArray(result.payload)) {
+        for (const device of result.payload) {
+          if (device.connectId) {
+            try {
+              const features = await sdk.getFeatures(device.connectId);
+              if (features?.success && features.payload) {
+                device.features = features.payload;
+                device.name = features.payload.label || features.payload.ble_name || device.name;
+                device.deviceType =
+                  features.payload.onekey_device_type?.toLowerCase() || device.deviceType;
+              }
+            } catch {
+              // Features fetch failed — device may need PIN, continue with basic info
+            }
+          }
+        }
+      }
+
       outputResult(globalOpts, result);
     } finally {
       sdk.dispose();
@@ -508,50 +513,30 @@ program
 
 program
   .command('firmware-update')
-  .description('Update device firmware')
-  .option('--version <ver>', 'Target firmware version (e.g., "4.8.0")')
-  .option('--platform <platform>', 'Platform: native | desktop | ext | web', 'desktop')
-  .action(async opts => {
-    const globalOpts = program.opts();
-    const sdk = await createSDK(globalOpts);
-    try {
-      // firmwareUpdateV2 requires: connectId, deviceId, { updateType, platform, version? }
-      const params: Record<string, unknown> = {
-        updateType: 'firmware',
-        platform: opts.platform,
-      };
-      if (opts.version) {
-        params.version = parseVersion(opts.version);
-      }
-      // firmwareUpdateV2 signature: (connectId, params) — 2 args only
-      const result = await sdk.firmwareUpdateV2(globalOpts.connectId, params as any);
-      outputResult(globalOpts, result);
-    } finally {
-      sdk.dispose();
-    }
+  .description('Firmware update is not supported via CLI')
+  .action(() => {
+    outputResult(program.opts(), {
+      success: false,
+      payload: {
+        error:
+          'Firmware update via CLI is not supported. Please use the OneKey App or https://firmware.onekey.so/ to update firmware.',
+        code: 'FIRMWARE_UPDATE_NOT_SUPPORTED',
+      },
+    });
   });
 
 program
   .command('firmware-update-ble')
-  .description('Update BLE (Bluetooth) firmware')
-  .option('--version <ver>', 'Target BLE firmware version')
-  .option('--platform <platform>', 'Platform: native | desktop | ext | web', 'desktop')
-  .action(async opts => {
-    const globalOpts = program.opts();
-    const sdk = await createSDK(globalOpts);
-    try {
-      const params: Record<string, unknown> = {
-        updateType: 'ble',
-        platform: opts.platform,
-      };
-      if (opts.version) {
-        params.version = parseVersion(opts.version);
-      }
-      const result = await sdk.firmwareUpdateV2(globalOpts.connectId, params as any);
-      outputResult(globalOpts, result);
-    } finally {
-      sdk.dispose();
-    }
+  .description('BLE firmware update is not supported via CLI')
+  .action(() => {
+    outputResult(program.opts(), {
+      success: false,
+      payload: {
+        error:
+          'BLE firmware update via CLI is not supported. Please use the OneKey App or https://firmware.onekey.so/ to update firmware.',
+        code: 'FIRMWARE_UPDATE_NOT_SUPPORTED',
+      },
+    });
   });
 
 program
@@ -622,66 +607,6 @@ program
     }
   });
 
-program
-  .command('device-backup')
-  .description('Trigger recovery phrase backup on device')
-  .action(async () => {
-    const globalOpts = program.opts();
-    const sdk = await createSDK(globalOpts);
-    try {
-      const result = await sdk.deviceBackup(globalOpts.connectId);
-      outputResult(globalOpts, result);
-    } finally {
-      sdk.dispose();
-    }
-  });
-
-program
-  .command('device-recovery')
-  .description('Recover wallet from recovery phrase (entered on device)')
-  .option('--word-count <count>', 'Recovery phrase length: 12, 18, or 24', '24')
-  .option('--passphrase-protection <bool>', 'Enable passphrase after recovery', 'false')
-  .option('--pin-protection <bool>', 'Set PIN after recovery', 'true')
-  .option('--label <name>', 'Device label')
-  .action(async opts => {
-    const globalOpts = program.opts();
-    const sdk = await createSDK(globalOpts);
-    try {
-      const result = await sdk.deviceRecovery(globalOpts.connectId, {
-        wordCount: safeParseInt(opts.wordCount, '--word-count'),
-        passphraseProtection: opts.passphraseProtection === 'true',
-        pinProtection: opts.pinProtection === 'true',
-        label: opts.label,
-      });
-      outputResult(globalOpts, result);
-    } finally {
-      sdk.dispose();
-    }
-  });
-
-program
-  .command('device-reset')
-  .description('Initialize device with a new wallet seed (DESTROYS current wallet)')
-  .option('--word-count <count>', 'Seed phrase length: 12, 18, or 24', '24')
-  .option('--passphrase-protection <bool>', 'Enable passphrase', 'false')
-  .option('--pin-protection <bool>', 'Set PIN', 'true')
-  .option('--label <name>', 'Device label')
-  .action(async opts => {
-    const globalOpts = program.opts();
-    const sdk = await createSDK(globalOpts);
-    try {
-      const result = await sdk.deviceReset(globalOpts.connectId, {
-        strength: wordCountToStrength(safeParseInt(opts.wordCount, '--word-count')),
-        passphraseProtection: opts.passphraseProtection === 'true',
-        pinProtection: opts.pinProtection === 'true',
-        label: opts.label,
-      });
-      outputResult(globalOpts, result);
-    } finally {
-      sdk.dispose();
-    }
-  });
-
 program
   .command('device-wipe')
   .description('Factory reset — erase ALL data (IRREVERSIBLE)')
@@ -784,29 +709,15 @@ function getCommonParams(globalOpts: Record<string, any>) {
   };
 }
 
-function outputResult(globalOpts: { json?: boolean }, result: unknown): void {
+function outputResult(_globalOpts: Record<string, any>, result: unknown): void {
   // #10 FIX: Always use JSON.stringify to avoid [Object] truncation
   console.log(JSON.stringify(result, null, 2));
 
-  // #11 FIX: Exit with code 1 on SDK failure
+  // Exit after output — SDK event listeners keep the process alive otherwise
   if (result && typeof result === 'object' && 'success' in result && !(result as any).success) {
-    process.exitCode = 1;
-  }
-}
-
-function wordCountToStrength(wordCount: number): number {
-  // #8 FIX: Validate word count is one of the allowed values
-  if (![12, 18, 24].includes(wordCount)) {
-    throw new Error(`Invalid word count: ${wordCount}. Must be 12, 18, or 24.`);
-  }
-  switch (wordCount) {
-    case 12:
-      return 128;
-    case 18:
-      return 192;
-    case 24:
-    default:
-      return 256;
+    process.exit(1);
+  } else {
+    process.exit(0);
   }
 }
 
@@ -841,15 +752,4 @@ function safeParseInt(input: string, label: string): number {
   return num;
 }
 
-/**
- * #15 FIX: Validate firmware version format
- */
-function parseVersion(input: string): number[] {
-  const parts = input.split('.').map(Number);
-  if (parts.length < 2 || parts.length > 4 || parts.some(Number.isNaN)) {
-    throw new Error(`Invalid version format: "${input}". Expected format: "4.8.0"`);
-  }
-  return parts;
-}
-
 program.parse();

package/src/index.ts

@@ -10,7 +10,7 @@
  *   npx @onekeyfe/hardware-cli get-address --chain evm
  *   npx @onekeyfe/hardware-cli sign-transaction --chain evm --tx '{...}'
  *
- * For AI agent integration, use --json flag for structured output.
+ * All output is structured JSON for AI agent consumption.
  *
  * IMPORTANT: All signing operations require physical confirmation on the
  * hardware device. The CLI handles PIN/Passphrase prompts via stdin for

package/src/sdk.ts

@@ -17,7 +17,6 @@ import * as readline from 'readline';
 import type { ConnectSettings } from '@onekeyfe/hd-core';
 
 export interface SDKOptions {
-  json?: boolean;
   connectId?: string;
   passphraseState?: string;
   useEmptyPassphrase?: boolean;
@@ -165,16 +164,18 @@ function registerEventHandlers(sdk: typeof HardwareSDK, opts: SDKOptions): void
     }
   });
 
-  // Device connection events
+  // Device connection events — only show when device has a known name
   sdk.on(DEVICE.CONNECT, (device: any) => {
-    if (!opts.json) {
-      process.stderr.write(`[onekey-hw] Device connected: ${device?.name || 'Unknown'}\n`);
+    const name = device?.label || device?.name;
+    if (name) {
+      process.stderr.write(`[onekey-hw] Device connected: ${name}\n`);
     }
   });
 
   sdk.on(DEVICE.DISCONNECT, (device: any) => {
-    if (!opts.json) {
-      process.stderr.write(`[onekey-hw] Device disconnected: ${device?.name || 'Unknown'}\n`);
+    const name = device?.label || device?.name;
+    if (name) {
+      process.stderr.write(`[onekey-hw] Device disconnected: ${name}\n`);
     }
   });
 }

package/skills/device/SKILL.md

@@ -1,191 +0,0 @@
----
-name: hardware-device
-description: OneKey hardware wallet device management. Use whenever the user
-  wants to search for, connect to, or check the status of their OneKey
-  hardware wallet device. Also triggered as a pre-check before any signing
-  or firmware operation to ensure a device is connected and ready.
-keywords: [device, connect, search, hardware, onekey, status, features, disconnect]
----
-
-## Pre-flight Checks
-
-Every time before running any `onekey-hw` command, follow these steps in order.
-Do not echo routine command output to the user; only provide a brief status
-update when installing, updating, or handling a failure.
-
-1. **Check CLI installed**: Run `onekey-hw --version`.
-   - Not found → install: `npm install -g @onekeyfe/hardware-cli`
-   - Install failed → STOP, point to manual install docs.
-
-2. **Check version is latest** (once per session):
-   - Fetch latest: `npm view @onekeyfe/hardware-cli version`
-   - Compare with local `onekey-hw --version`
-   - Local version behind → **BLOCK operation**, run `npm update -g @onekeyfe/hardware-cli`
-   - Update failed → STOP, suggest manual update.
-   - Update succeeded → continue with original command.
-
-## Device Interaction Model
-
-**CRITICAL: Most `onekey-hw` commands block while waiting for physical interaction
-on the hardware device (PIN entry, button confirmation, address verification).
-You MUST inform the user BEFORE running the command.**
-
-### How It Works
-
-1. **Before running the command** → Tell the user what device interaction to expect.
-2. **Run the command** → It blocks (up to 60s) while waiting for the user to act on the device.
-   The user sees real-time `[onekey-hw]` status messages in their terminal (via stderr).
-3. **Command completes** → You see the full output and present the result.
-
-### Device Interaction Types
-
-| Stderr Message | What User Must Do | When It Happens |
-|---|---|---|
-| `[onekey-hw] Please enter PIN on your device screen...` | Enter PIN on device touchscreen | First operation after device lock/connect |
-| `[onekey-hw] Please confirm the action on your device...` | Press confirm button on device | Address display, signing, settings changes |
-| `[onekey-hw] Passphrase required for hidden wallet.` | Enter passphrase on device | When accessing a hidden wallet |
-
-### Timeout Guidance
-
-- Set Bash tool `timeout` to at least `120000` (120s) for any command that requires
-  device interaction (signing, address with `--show-on-device`, PIN changes, etc.)
-- `search` does NOT require device interaction — default timeout is fine.
-- If a command times out, the user likely did not respond on the device — do NOT retry
-  automatically. Ask the user if they want to try again.
-
-### Example Interaction Pattern
-
-```
-Agent → User: "I'm going to request your ETH address from the device.
-              You may need to enter your PIN and confirm on the device screen."
-Agent → Bash: onekey-hw get-address --chain evm --connect-id <id>  (timeout: 120000)
-[user sees in terminal: "[onekey-hw] Please enter PIN on your device screen..."]
-[user enters PIN on device]
-[user sees in terminal: "[onekey-hw] Please confirm the action on your device..."]
-[user confirms on device]
-Agent ← result: { success: true, payload: { address: "0x..." } }
-Agent → User: "Your ETH address is 0x..."
-```
-
-## Security Rules — ABSOLUTE
-
-- NEVER expose device seeds, mnemonics, or private keys in any output.
-- All signing operations REQUIRE physical confirmation on the hardware device.
-- NEVER bypass device confirmation prompts — if the device is waiting for user
-  confirmation, inform the user and wait.
-- NEVER attempt to brute-force PINs or passphrases.
-- Treat all device state information (features, serial numbers) as sensitive —
-  do not share externally without user consent.
-
-## Parameter Rules
-
-### Device Identification
-
-- `--connect-id`: Connection identifier from `search` results.
-- `--device-id`: Persistent device identifier from `getFeatures`.
-- When multiple devices connected, ALWAYS ask user to select.
-
-## Commands
-
-### `onekey-hw search`
-
-Search for connected OneKey hardware wallet devices.
-**Does NOT require device interaction — no PIN or confirmation needed.**
-
-```bash
-onekey-hw search [--timeout <ms>]
-```
-
-| Parameter | Required | Description |
-|---|---|---|
-| `--timeout` | No | Search timeout in milliseconds (default: 10000) |
-
-**Returns:**
-```json
-{
-  "success": true,
-  "payload": [
-    {
-      "connectId": "PRC49J0370A",
-      "name": "OneKey Pro",
-      "deviceType": "pro"
-    }
-  ]
-}
-```
-
-**Agent notes:**
-- Always run `search` before any device operation if no `connectId` is known.
-- If no devices found, suggest: check USB cable, unlock device, try a different USB port.
-- Multiple devices → present list, ask user to select.
-
-### `onekey-hw status`
-
-Get detailed device features and current status.
-**May require PIN entry on device if device is locked.**
-
-```bash
-onekey-hw status [--connect-id <id>]
-```
-
-**Agent notes:**
-- Use this to verify device state before any operation.
-- If `initialized` is false, guide user through device setup.
-- If `needsBackup` is true, strongly recommend backup before any signing.
-- If `bootloaderMode` is true, only firmware operations are available.
-- **Warn user before running:** "You may need to enter your PIN on the device."
-
-### `onekey-hw lock`
-
-Lock the device (require PIN to unlock).
-
-```bash
-onekey-hw lock [--connect-id <id>]
-```
-
-## Workflows
-
-### First Connection
-
-```
-User: "Connect my OneKey hardware wallet"
-
-Step 1 — Search for devices (no device interaction needed)
-→ onekey-hw search --json
-→ If no devices found, guide troubleshooting (USB cable, unlock, different port)
-
-Step 2 — Tell user what to expect
-→ "Found your OneKey Pro. I'll check its status now — you may need to enter
-   your PIN on the device."
-
-Step 3 — Check device status (may need PIN)
-→ onekey-hw status --connect-id <id>  [timeout: 120000]
-→ Report: model, firmware version, PIN status, backup status
-```
-
-### Troubleshooting Connection
-
-```
-User: "My device won't connect"
-
-Step 1 — Search with extended timeout
-→ onekey-hw search --timeout 30000
-
-Step 2 — Guide the user:
-  - Is the device powered on and unlocked?
-  - Try a different USB cable or port
-  - On Linux, check udev rules for HID device permissions
-```
-
-## When To Use
-
-- User asks to connect, find, or search for their hardware wallet.
-- User asks about device status, firmware version, or device info.
-- Pre-check before any signing or firmware operation.
-- User reports connection issues.
-
-## When NOT To Use
-
-- User wants to sign a transaction → use `hardware-signing`.
-- User wants to update firmware → use `hardware-firmware`.
-- User wants to change PIN or passphrase → use `hardware-security`.

package/skills/firmware/SKILL.md

@@ -1,163 +0,0 @@
----
-name: hardware-firmware
-description: OneKey hardware wallet firmware management. Use whenever the user
-  wants to check for firmware updates, update their device firmware (system
-  or BLE), check bootloader status, or verify firmware compatibility.
-keywords: [firmware, update, version, upgrade, bootloader, ble, bluetooth]
----
-
-## Pre-flight Checks
-
-Every time before running any `onekey-hw` command, follow these steps in order.
-
-1. **Check CLI installed**: Run `onekey-hw --version`.
-   - Not found → install: `npm install -g @onekeyfe/hardware-cli`
-
-2. **Check device connected**: Run `onekey-hw search --json`.
-   - No device → guide troubleshooting (USB cable, unlock device, different port).
-
-## Device Interaction — IMPORTANT
-
-**Firmware commands block while waiting for device interaction (PIN, confirmation).**
-Always warn the user before running: "You may need to enter your PIN and confirm
-on the device." Use `timeout: 300000` (5 minutes) for firmware update commands —
-updates take 1-3 minutes to complete.
-
-## Security Rules — ABSOLUTE
-
-### Firmware Update Safety
-
-- NEVER interrupt a firmware update in progress — this can BRICK the device.
-- ALWAYS ensure the device has sufficient battery before starting (if applicable).
-- ALWAYS confirm with the user before starting a firmware update:
-  "Firmware updates modify your device's system software. Do NOT disconnect
-  the device during the update. Continue?"
-- After firmware update, the device may require re-entering the PIN.
-- Firmware updates do NOT erase wallet data (seeds are preserved in the secure element).
-
-### Bootloader Safety
-
-- If the device is in bootloader mode, only firmware update operations are available.
-- NEVER attempt to exit bootloader mode during an active update.
-- If the device is stuck in bootloader mode unexpectedly, guide the user to
-  contact OneKey support.
-
-## Commands
-
-### `onekey-hw firmware-check`
-
-Check if a firmware update is available for the connected device.
-
-```bash
-onekey-hw firmware-check [--connect-id <id>]
-```
-
-**Agent notes:**
-- Always check firmware before any operation to ensure compatibility.
-- If `required` is true, the update is mandatory — signing may not work until updated.
-- Present changelog to user so they can make an informed decision.
-
-### `onekey-hw firmware-check-all`
-
-Check all firmware components at once (system, BLE, bootloader).
-
-```bash
-onekey-hw firmware-check-all [--connect-id <id>]
-```
-
-### `onekey-hw firmware-update`
-
-Update the device firmware (system firmware).
-
-```bash
-onekey-hw firmware-update \
-  [--connect-id <id>] \
-  [--version <version>] \
-  [--platform <platform>]
-```
-
-| Parameter | Required | Description |
-|---|---|---|
-| `--connect-id` | No | Device connection ID |
-| `--version` | No | Target version, e.g. "4.8.0" (defaults to latest) |
-| `--platform` | No | Platform: native, desktop, ext, web (default: desktop) |
-
-**Agent notes:**
-- This operation takes 1-3 minutes. Inform the user to be patient.
-- The device will reboot during the update — this is normal.
-- After update, run `onekey-hw search` again to re-detect the device.
-- If the update fails, the device may enter bootloader mode — guide recovery.
-
-### `onekey-hw firmware-update-ble`
-
-Update the BLE (Bluetooth) firmware.
-
-```bash
-onekey-hw firmware-update-ble \
-  [--connect-id <id>] \
-  [--version <version>] \
-  [--platform <platform>]
-```
-
-**Agent notes:**
-- BLE update is separate from system firmware update.
-- Only applicable for devices with Bluetooth capability (Touch, Pro).
-- After BLE update, Bluetooth pairing may need to be re-established.
-
-### `onekey-hw bootloader-check`
-
-Check bootloader version and status.
-
-```bash
-onekey-hw bootloader-check [--connect-id <id>]
-```
-
-## Workflows
-
-### Check & Update Firmware
-
-```
-User: "Is my firmware up to date?"
-
-Step 1 — Check all components
-→ onekey-hw firmware-check-all --connect-id <id> --json
-→ Present results in a clear table
-
-Step 2 — If updates available, ask user
-→ "BLE firmware v2.1.0 is available (current: v2.0.0). Changes: Improved BLE stability."
-→ "Would you like to update?"
-
-Step 3 — User confirms → update
-→ "DO NOT disconnect your device during the update."
-→ onekey-hw firmware-update-ble --connect-id <id>
-→ "BLE firmware updated to v2.1.0."
-```
-
-### Recover from Bootloader Mode
-
-```
-User: "My device shows a bootloader screen"
-
-Step 1 — Verify bootloader mode
-→ onekey-hw status --connect-id <id>
-→ If bootloaderMode: true, proceed
-
-Step 2 — Attempt firmware update to recover
-→ "Your device is in bootloader mode. This usually means a firmware update
-   was interrupted. Let's reinstall the firmware."
-→ onekey-hw firmware-update --connect-id <id>
-→ "Firmware installed. Your device should restart normally."
-```
-
-## When To Use
-
-- User asks about firmware versions or updates.
-- User wants to update device firmware.
-- Device is in bootloader mode and needs recovery.
-- Pre-check before signing to ensure firmware compatibility.
-
-## When NOT To Use
-
-- User wants to sign transactions → use `hardware-signing`.
-- User wants to connect devices → use `hardware-device`.
-- User wants to change PIN/passphrase → use `hardware-security`.