@onekeyfe/hardware-cli 1.1.25-alpha.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@onekeyfe/hardware-cli",
+  "version": "1.1.25-alpha.0",
+  "description": "OneKey hardware wallet CLI for AI agent integration",
+  "author": "OneKey",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/OneKeyHQ/hardware-js-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OneKeyHQ/hardware-js-sdk.git"
+  },
+  "bin": {
+    "onekey-hw": "./dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "rimraf dist && rollup -c rollup.config.js -w",
+    "build": "rimraf dist && rollup -c rollup.config.js && node -e \"const f='dist/cli.js';const c=require('fs').readFileSync(f,'utf8');require('fs').writeFileSync(f,'#!/usr/bin/env node\\n'+c)\"",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "dependencies": {
+    "@onekeyfe/hd-common-connect-sdk": "1.1.25-alpha.0",
+    "@onekeyfe/hd-core": "1.1.25-alpha.0",
+    "@onekeyfe/hd-shared": "1.1.25-alpha.0",
+    "@onekeyfe/hd-transport-usb": "1.1.25-alpha.0",
+    "commander": "^12.0.0"
+  },
+  "gitHead": "8cebdb9dea32ab8bfa39c51cd695f5cd9508defa"
+}

package/rollup.config.js

@@ -0,0 +1,28 @@
+import typescript from '@rollup/plugin-typescript';
+import json from '@rollup/plugin-json';
+import dts from 'rollup-plugin-dts';
+import commonjs from '@rollup/plugin-commonjs';
+
+const config = [
+  // All source files → dist/ directory (cjs format)
+  // This outputs index.js, cli.js, sdk.js, chains.js all to dist/
+  // so cli.js can require('./sdk') and require('./chains')
+  {
+    input: {
+      index: './src/index.ts',
+      cli: './src/cli.ts',
+      sdk: './src/sdk.ts',
+      chains: './src/chains.ts',
+    },
+    output: [{ dir: 'dist', format: 'cjs' }],
+    plugins: [typescript(), commonjs(), json()],
+  },
+  // Type declarations
+  {
+    input: './src/index.ts',
+    output: { file: 'dist/index.d.ts', format: 'es' },
+    plugins: [dts()],
+  },
+];
+
+export default config;

package/skills/device/SKILL.md

@@ -0,0 +1,191 @@
+---
+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

@@ -0,0 +1,163 @@
+---
+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`.