@esp-vision/device-core 0.4.2 → 0.5.1

package/tests/test-node-inventory.mjs

@@ -0,0 +1,136 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import {
+  defaultPython, filterSerialPorts, inventory, listSerial, serialEntry, transportFor,
+} from '../src/node.js'
+
+test('the public Node entry point exposes passive inventory and serial adapters', () => {
+  assert.equal(typeof defaultPython, 'string')
+  assert.equal(typeof listSerial, 'function')
+  assert.equal(typeof filterSerialPorts, 'function')
+  assert.equal(typeof serialEntry, 'function')
+  assert.equal(typeof transportFor, 'function')
+  assert.equal(typeof inventory, 'function')
+})
+
+test('serial listing passes a bounded non-opening enumeration request to Python', async () => {
+  const controller = new AbortController()
+  let invocation
+  const ports = await listSerial({ python: 'python-test', signal: controller.signal, timeout: 2345 }, {
+    async execFile(command, args, options) {
+      invocation = { command, args, options }
+      return { stdout: '[{"path":"/dev/ttyACM0","vendorId":1234}]' }
+    },
+  })
+
+  assert.deepEqual(ports, [{ path: '/dev/ttyACM0', vendorId: 1234 }])
+  assert.equal(invocation.command, 'python-test')
+  assert.match(invocation.args[0], /node_serial\.py$/)
+  assert.deepEqual(invocation.args.slice(1), ['--list'])
+  assert.equal(invocation.options.signal, controller.signal)
+  assert.equal(invocation.options.timeout, 2345)
+  assert.equal(invocation.options.maxBuffer, 1024 * 1024)
+  assert.equal(invocation.options.windowsHide, true)
+})
+
+test('serial enumeration reports a bounded-process timeout and preserves cancellation', async () => {
+  const timedOut = Object.assign(new Error('private process details'), { code: 'ETIMEDOUT' })
+  await assert.rejects(
+    listSerial({ timeout: 250 }, { execFile: async () => { throw timedOut } }),
+    error => error.code === 'TIMEOUT' && error.cause === timedOut && !error.message.includes('private'),
+  )
+
+  const controller = new AbortController()
+  const reason = new Error('cancelled')
+  const pending = listSerial({ signal: controller.signal }, {
+    execFile: async (_command, _args, options) => new Promise((_resolve, reject) => {
+      options.signal.addEventListener('abort', () => reject(reason), { once: true })
+    }),
+  })
+  controller.abort(reason)
+  await assert.rejects(pending, error => error === reason)
+})
+
+test('serial candidate filtering stays platform-aware and classification is descriptor-only', () => {
+  const ports = [
+    { path: '/dev/ttyACM0', vendorId: 0x303a, productId: 0x1001, product: 'USB JTAG/serial' },
+    { path: '/dev/ttyUSB0' },
+    { path: '/dev/ttyS0' },
+  ]
+  assert.deepEqual(filterSerialPorts(ports, { platform: 'linux' }), ports.slice(0, 2))
+  assert.deepEqual(filterSerialPorts(ports, { platform: 'linux', allPorts: true }), ports)
+  const entry = serialEntry(ports[0])
+  assert.equal(entry.interface, 'usj')
+  assert.equal(entry.status, 'unprobed')
+  assert.equal(entry.identity, null)
+  const transport = transportFor(entry, { python: 'python-test' })
+  assert.equal(typeof transport.connect, 'function')
+})
+
+test('inventory forwards timeout and cancellation without probing by default', async () => {
+  const controller = new AbortController()
+  let serialRequest
+  let opened = 0
+  const result = await inventory({ interfaces: ['serial'], timeout: 750, signal: controller.signal }, {
+    platform: 'linux',
+    async listSerial(request) {
+      serialRequest = request
+      return [{ path: '/dev/ttyACM1', vendorId: 0x303a, productId: 0x1001 }]
+    },
+    createDevice() {
+      opened += 1
+      throw new Error('passive inventory opened a serial port')
+    },
+  })
+
+  assert.equal(serialRequest.timeout, 750)
+  assert.equal(serialRequest.signal, controller.signal)
+  assert.equal(opened, 0)
+  assert.equal(result.devices.length, 1)
+  assert.equal(result.devices[0].address, '/dev/ttyACM1')
+  assert.equal(result.devices[0].status, 'unprobed')
+  assert.equal(result.devices[0].identity, null)
+})
+
+test('explicit inventory probing acquires and reads metadata without interrupting the REPL', async () => {
+  const controller = new AbortController()
+  let connection, inspection, disconnected = false
+  const result = await inventory({
+    interfaces: ['serial'], probe: true, probeTimeout: 1250, signal: controller.signal,
+  }, {
+    platform: 'linux',
+    async listSerial() { return [{ path: '/dev/ttyUSB7', vendorId: 0x1234 }] },
+    transportFor(row) { return { address: row.address } },
+    createDevice() {
+      return {
+        async connect(options) {
+          connection = options
+          return { identity: { deviceId: 'e8f60ae75642', board: 'TEST' } }
+        },
+        async inspect(options) { inspection = options; return { runtime: { vmReady: false } } },
+        async disconnect() { disconnected = true },
+      }
+    },
+  })
+
+  assert.equal(connection.role, 'unknown')
+  assert.equal(connection.timeout, 1250)
+  assert.equal(connection.signal, controller.signal)
+  assert.equal(connection.probeRepl, false)
+  assert.equal(inspection.signal, controller.signal)
+  assert.equal(disconnected, true)
+  assert.equal(result.devices[0].status, 'identified')
+  assert.deepEqual(result.devices[0].inspection, { runtime: { vmReady: false } })
+})
+
+test('inventory propagates an aborted serial enumeration', async () => {
+  const reason = new Error('cancelled')
+  await assert.rejects(
+    inventory({ interfaces: ['serial'], signal: AbortSignal.abort(reason) }, {
+      async listSerial({ signal }) { throw signal.reason },
+    }),
+    error => error === reason,
+  )
+})

package/tests/test-node-serial.mjs

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { delimiter, dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { test } from 'node:test'
+import { createDevice } from '../src/device.js'
+import { serialTransport } from '../src/node_transport.js'
+
+const coreRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const adapter = join(coreRoot, 'src/node_serial.py')
+const tempBase = resolve(process.env.ESP_VISION_NPM_TEMP_DIR ?? process.env.TMPDIR ?? join(coreRoot, '.cache/node-serial'))
+const python = [process.env.PYTHON, 'python3', 'python'].filter(Boolean).find(candidate => {
+  const result = spawnSync(candidate, ['-c', 'pass'], { encoding: 'utf8', windowsHide: true })
+  return result.status === 0
+})
+
+async function createSerialFixture() {
+  await mkdir(tempBase, { recursive: true })
+  const root = await mkdtemp(join(tempBase, 'serial-lock-'))
+  const moduleDir = join(root, 'python')
+  await mkdir(moduleDir, { recursive: true })
+  const stateFile = join(root, 'open-state.json')
+  const serialModule = `
+import json
+
+class SerialException(Exception):
+    pass
+
+class Serial:
+    def __init__(self, *args, **kwargs):
+        self.rts = None
+        self.dtr = None
+        self.port = None
+        self.exclusive = None
+
+    def open(self):
+        with open(${JSON.stringify(stateFile)}, 'w', encoding='utf-8') as stream:
+            json.dump({'port': self.port, 'rts': self.rts, 'dtr': self.dtr, 'exclusive': self.exclusive}, stream)
+        raise SerialException('Could not exclusively lock port /dev/fixture: [Errno 11] Resource temporarily unavailable')
+
+    def close(self):
+        pass
+`
+  await writeFile(join(moduleDir, 'serial.py'), serialModule)
+  return { root, moduleDir, stateFile }
+}
+
+function fixturePythonEnv(moduleDir) {
+  return {
+    ...process.env,
+    PYTHONPATH: [moduleDir, process.env.PYTHONPATH].filter(Boolean).join(delimiter),
+  }
+}
+
+test('POSIX serial open requests an exclusive lock and exposes SERIAL_BUSY', {
+  skip: !python || process.platform === 'win32',
+}, async (t) => {
+  const fixture = await createSerialFixture()
+  t.after(() => rm(fixture.root, { recursive: true, force: true }))
+  const previousPythonPath = process.env.PYTHONPATH
+  process.env.PYTHONPATH = [fixture.moduleDir, previousPythonPath].filter(Boolean).join(delimiter)
+  t.after(() => {
+    if (previousPythonPath === undefined) delete process.env.PYTHONPATH
+    else process.env.PYTHONPATH = previousPythonPath
+  })
+
+  const direct = spawnSync(python, ['-u', adapter, '/dev/fixture'], {
+    env: fixturePythonEnv(fixture.moduleDir),
+    encoding: 'utf8',
+    windowsHide: true,
+  })
+  assert.equal(direct.status, 2, direct.stderr || direct.error?.message || 'Python adapter fixture did not fail as expected')
+  assert.equal(direct.stderr.trim(), 'SERIAL_BUSY')
+  const opened = JSON.parse(await readFile(fixture.stateFile, 'utf8'))
+  assert.deepEqual(opened, { port: '/dev/fixture', rts: false, dtr: true, exclusive: true })
+  await rm(fixture.stateFile)
+
+  const device = createDevice({ transport: serialTransport({ python, serial: '/dev/fixture' }) })
+  t.after(() => device.disconnect())
+  await assert.rejects(device.connect({ timeout: 5000 }), { code: 'SERIAL_BUSY' })
+  assert.deepEqual(JSON.parse(await readFile(fixture.stateFile, 'utf8')), opened)
+})
+
+test('non-POSIX serial backends do not receive the unsupported exclusive option', {
+  skip: !python,
+}, async () => {
+  const source = [
+    'import importlib.util, sys, types',
+    'sys.modules["serial"] = types.SimpleNamespace()',
+    'spec = importlib.util.spec_from_file_location("node_serial", sys.argv[1])',
+    'module = importlib.util.module_from_spec(spec)',
+    'spec.loader.exec_module(module)',
+    'port = types.SimpleNamespace()',
+    'module._configure_serial_exclusive(port, "nt")',
+    'assert not hasattr(port, "exclusive")',
+  ].join('\n')
+  const result = spawnSync(python, ['-c', source, adapter], {
+    encoding: 'utf8',
+    windowsHide: true,
+  })
+  assert.equal(result.status, 0, result.stderr || result.error?.message || 'Python fixture failed')
+})

package/src/cli.js

@@ -1,185 +0,0 @@
-#!/usr/bin/env node
-// SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
-// SPDX-License-Identifier: Apache-2.0
-import { parseArgs } from 'node:util'
-import { readFile } from 'node:fs/promises'
-import { realpathSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
-import { createInterface } from 'node:readline/promises'
-import { Writable } from 'node:stream'
-import stringWidth from 'string-width'
-import { createDevice } from './index.js'
-import { openNodeRom } from './node_rom.js'
-import { inventory, transportFor, defaultPython } from './node_inventory.js'
-
-export const usage = `esp-vision-device inspect [--port PATH | --tcp HOST[:PORT] | --select N]
-  [--fields identity,capabilities,runtime,network,storage] [--probe]
-  [--interface all|serial|usb|usj|uart|tcp] [--all-ports] [--json]
-esp-vision-device configure (--port PATH | --tcp HOST[:PORT])
-  [--ssid SSID [--password-stdin]] [--forget-wifi] [--network-enabled true|false]
-esp-vision-device control (--port PATH | --tcp HOST[:PORT])
-  --action stop|reset|bootloader [--mode soft|hard]
-esp-vision-device firmware check [--port PATH | --tcp HOST[:PORT]]
-  [--catalog FILE|HTTPS_URL] [--board BOARD --current-version VERSION] [--version VERSION] [--mode update|install]
-esp-vision-device firmware update [--port PATH | --tcp HOST[:PORT]]
-  [--catalog FILE|HTTPS_URL] --version VERSION [--image FIRMWARE.bin] [--mode update|install]
-  [--board BOARD --current-version VERSION]
-Common: --timeout MS (default 3000 enumeration, 30000 command),
-  --probe-timeout MS (default 5000 per device), --role usb|usj|uart|unknown,
-  --python PYTHON (default python3; Windows python), --json, --help
-Default inspect enumerates USB serial ports and LAN advertisements; --all-ports
-also includes native UART/Bluetooth ports. No serial
-port is opened. --probe and targeted commands acquire a session and can interrupt
-Python. Rows with unknown firmware remain visible; numbering is per invocation.
-Firmware versions come from dl.espressif.com by default; local catalogs are advanced overrides.
-Firmware update uses the built-in serial flasher (Python esptool>=5.3,<6). TCP is not OTA.
-Default mode update preserves the existing layout/data; explicit mode install writes
-a complete image, replacing data in its written range. Blank boards require --board
-and a ROM-capable USJ/UART port, not an application USB-OTG interface.`
-const error = (code, message) => Object.assign(new Error(message), { code })
-const fields = ['identity', 'capabilities', 'runtime', 'network', 'storage']
-export function parseCli(args) {
-  const boolean = ['help', 'json', 'all-ports', 'probe', 'forget-wifi', 'password-stdin']
-  const string = ['port', 'tcp', 'select', 'fields', 'interface', 'python', 'timeout', 'probe-timeout', 'role', 'ssid', 'network-enabled', 'action', 'mode', 'catalog', 'board', 'current-version', 'version', 'image']
-  const { values: v, positionals: p } = parseArgs({ args, allowPositionals: true, options: Object.fromEntries([...boolean.map(key => [key, { type: 'boolean' }]), ...string.map(key => [key, { type: 'string' }])]) })
-  if (v.help) return { help: true }
-  const command = p[0] ?? 'inspect', action = command === 'firmware' ? p[1] : null
-  if (!['inspect', 'configure', 'control', 'firmware'].includes(command) || p.length > (command === 'firmware' ? 2 : 1) || (command === 'firmware' && !['check', 'update'].includes(action))) throw error('ARGUMENT', 'Unknown command; use --help')
-  const allowed = { inspect: ['all-ports', 'select', 'fields', 'interface', 'probe', 'probe-timeout'], configure: ['ssid', 'forget-wifi', 'password-stdin', 'network-enabled'], control: ['action', 'mode'], firmware: ['mode', 'catalog', 'board', 'current-version', 'version', 'image'] }[command]
-  for (const key of Object.keys(v)) if (!['json', 'port', 'tcp', 'python', 'timeout', 'role', ...allowed].includes(key)) throw error('ARGUMENT', `Option --${key} is not valid for ${command}`)
-  if ([v.port, v.tcp, v.select].filter(value => value !== undefined).length > 1) throw error('ARGUMENT', 'Select exactly one device address or number')
-  if (v.role && !['usb', 'usj', 'uart', 'unknown'].includes(v.role)) throw error('ARGUMENT', 'Invalid serial role')
-  if (v.role && !v.port) throw error('ARGUMENT', '--role requires --port')
-  if (v.select !== undefined && (!/^\d+$/.test(v.select) || Number(v.select) < 1)) throw error('ARGUMENT', '--select must be a positive result number')
-  const timeout = Number(v.timeout ?? (command === 'inspect' && !v.port && !v.tcp ? 3000 : 30000))
-  if (!Number.isSafeInteger(timeout) || timeout < 50 || timeout > 600000) throw error('ARGUMENT', 'Timeout must be 50..600000 ms')
-  const interfaces = (v.interface ?? 'all').split(',')
-  if (interfaces.some(value => !['all', 'serial', 'usb', 'usj', 'uart', 'tcp'].includes(value))) throw error('ARGUMENT', 'Unknown interface filter')
-  const selectedFields = v.fields?.split(',')
-  if (selectedFields?.some(value => !fields.includes(value))) throw error('ARGUMENT', 'Unknown inspect field')
-  if (selectedFields && !v.port && !v.tcp && !v.probe && !v.select) throw error('ARGUMENT', '--fields requires a target, --select or --probe')
-  const probeTimeout = Number(v['probe-timeout'] ?? 5000)
-  if (!Number.isSafeInteger(probeTimeout) || probeTimeout < 50 || probeTimeout > 60000) throw error('ARGUMENT', 'Probe timeout must be 50..60000 ms')
-  let endpoint
-  if (v.tcp) {
-    const m = /^(?:\[([0-9a-fA-F:]+)\]|([^\s:/@?#]+))(?::([0-9]+))?$/.exec(v.tcp)
-    if (!m || Number(m[3] ?? 3232) < 1 || Number(m[3] ?? 3232) > 65535) throw error('ARGUMENT', 'Expected TCP host[:port] without credentials or URL')
-    endpoint = { interface: 'tcp', host: m[1] ?? m[2], port: Number(m[3] ?? 3232), address: v.tcp }
-  }
-  if (v.port) endpoint = { interface: v.role ?? 'unknown', address: v.port }
-  if (command === 'configure' || command === 'control') {
-    if (!endpoint) throw error('ARGUMENT', 'Specify --port or --tcp')
-  }
-  if (command === 'configure') {
-    if (v['network-enabled'] !== undefined && !['true', 'false'].includes(v['network-enabled'])) throw error('ARGUMENT', 'network-enabled must be true or false')
-    if ((v.ssid && v['forget-wifi']) || (v['password-stdin'] && !v.ssid) || (!v.ssid && !v['forget-wifi'] && v['network-enabled'] === undefined)) throw error('ARGUMENT', 'Specify SSID, forget-wifi or network-enabled')
-  }
-  if (command === 'control' && (!['stop', 'reset', 'bootloader'].includes(v.action) || (v.action === 'reset' ? !['soft', 'hard'].includes(v.mode) : v.mode !== undefined))) throw error('ARGUMENT', 'Control requires action; reset requires mode soft or hard')
-  if (command === 'firmware') {
-    if (v.mode !== undefined && !['update', 'install'].includes(v.mode)) throw error('ARGUMENT', 'Firmware mode must be update or install')
-    if (v.mode === 'install' && !v.board) throw error('ARGUMENT', 'Firmware installation requires explicit --board')
-    if (!endpoint && !v.board) throw error('ARGUMENT', 'Firmware requires a connected device or --board')
-    if (action === 'update' && (!v.port || !v.version)) throw error('ARGUMENT', 'Firmware update requires local --port and explicit --version')
-    if (action === 'check' && v.image) throw error('ARGUMENT', 'Image applies only to firmware update')
-  }
-  return { ...v, allPorts: v['all-ports'] ?? false, command, action: command === 'firmware' ? action : v.action, endpoint, timeout, probeTimeout, interfaces, fields: selectedFields, select: v.select === undefined ? undefined : Number(v.select), python: v.python ?? defaultPython }
-}
-async function passwordFromInput(options) {
-  if (options['password-stdin']) {
-    let value = ''
-    for await (const chunk of process.stdin) { value += chunk; if (value.length > 4096) throw error('ARGUMENT', 'Password input is too long') }
-    return value.replace(/\r?\n$/, '')
-  }
-  if (!process.stdin.isTTY) throw error('ARGUMENT', 'Use --password-stdin for non-interactive Wi-Fi configuration')
-  process.stderr.write('Wi-Fi password (hidden; empty for open network): ')
-  const output = new Writable({ write(_chunk, _encoding, callback) { callback() } })
-  const terminal = createInterface({ input: process.stdin, output, terminal: true })
-  terminal.once('SIGINT', () => process.kill(process.pid, 'SIGINT'))
-  try { return await terminal.question('', { signal: options.signal }) } finally { terminal.close(); process.stderr.write('\n') }
-}
-export async function runCli(options, dependencies = {}) {
-  if (options.help) return { help: usage }
-  const signal = dependencies.signal
-  const makeDevice = dependencies.createDevice ?? createDevice
-  const scan = dependencies.inventory ?? inventory
-  let endpoint = options.endpoint
-  if (options.command === 'inspect' && !endpoint) {
-    const listing = await scan({ ...options, signal, timeout: Math.min(options.timeout, 10000) }, dependencies)
-    if (!options.select) {
-      if (listing.sourcesAvailable === 0) throw error('ENUMERATION_UNAVAILABLE', 'No inventory source succeeded; check Python/pyserial, multicast-dns and permissions')
-      return listing
-    }
-    endpoint = listing.devices.find(row => row.number === options.select)
-    if (!endpoint) throw error('DEVICE_NOT_FOUND', 'Selected result number is unavailable in this enumeration')
-  }
-  const offline = options.command === 'firmware' && options.board
-  const device = makeDevice(endpoint && !offline ? { transport: (dependencies.transportFor ?? transportFor)(endpoint, options) } : {})
-  try {
-    if (endpoint && !offline) await device.connect({ role: endpoint.interface === 'serial' ? 'unknown' : endpoint.interface, timeout: options.timeout, signal, ...(endpoint.advertisement ? { expectedDevice: endpoint.advertisement } : {}) })
-    if (options.command === 'inspect') return await device.inspect({ fields: options.fields, timeout: options.timeout, signal })
-    if (options.command === 'configure') {
-      const network = {}
-      if (options.ssid) network.credentials = { ssid: options.ssid, password: await (dependencies.readPassword ?? passwordFromInput)({ ...options, signal }) }
-      if (options['forget-wifi']) network.credentials = null
-      if (options['network-enabled'] !== undefined) network.enabled = options['network-enabled'] === 'true'
-      await device.configure({ network, timeout: options.timeout, signal })
-      return { ok: true } // Do not echo credentials or configuration payloads.
-    }
-    if (options.command === 'control') return await device.control({ action: options.action, ...(options.mode ? { mode: options.mode } : {}), timeout: options.timeout, signal })
-    let catalog = options.catalog
-    const mode = options.mode ?? 'update'
-    if (catalog !== undefined && !/^https:\/\//.test(catalog)) catalog = JSON.parse(await (dependencies.readFile ?? readFile)(catalog, 'utf8'))
-    const checked = await device.firmware.check({ catalog, mode, ...(endpoint && !offline ? {} : { identity: { board: options.board, firmwareVersion: options['current-version'] ?? 'unknown' } }), ...(options.version ? { version: options.version } : {}), signal })
-    if (options.action === 'check') return checked
-    return await device.firmware.update({ mode, release: checked.release, board: options.board, ...(options.image ? { data: new Uint8Array(await (dependencies.readFile ?? readFile)(options.image)) } : {}), openLoader: ({ signal }) => (dependencies.openLoader ?? openNodeRom)({ port: options.port, python: options.python, signal }), onPhase: dependencies.onPhase ?? (() => {}), signal })
-  } finally { await device.disconnect() }
-}
-const safe = value => String(value ?? '—').replace(/[\x00-\x1f\x7f-\x9f]/g, '?')
-const graphemes = new Intl.Segmenter(undefined, { granularity: 'grapheme' })
-function wrapCell(value, width) {
-  const lines = []; let line = '', used = 0
-  for (const { segment } of graphemes.segment(value)) {
-    const size = stringWidth(segment)
-    if (used + size > width && line) { lines.push(line); line = ''; used = 0 }
-    line += segment; used += size
-  }
-  lines.push(line)
-  return lines
-}
-export function formatResult(result, { columns = process.stdout.columns ?? 120 } = {}) {
-  if (!result.devices) return JSON.stringify(result, null, 2)
-  const headers = ['#', 'Group', 'Interface', 'Address', 'Status', 'Board', 'Firmware', 'Device ID', 'USB serial', 'Hostname', 'USB VID:PID', 'USB product', 'Error']
-  const rows = result.devices.map(row => [row.number, row.group, row.interface, row.address, row.status, row.identity?.board, row.identity?.firmwareVersion, row.identity?.deviceId, row.usb?.serialNumber, row.identity?.hostname, row.usb?.vendorId == null ? null : `${row.usb.vendorId.toString(16).padStart(4, '0')}:${(row.usb.productId ?? 0).toString(16).padStart(4, '0')}`, row.usb?.product, row.error?.code].map(safe))
-  if (!rows.length) return 'No devices found.'
-  const widths = headers.map((header, index) => Math.max(stringWidth(header), ...rows.map(row => stringWidth(row[index]))))
-  if (widths.reduce((sum, width) => sum + width, 0) + 2 * (headers.length - 1) <= columns) {
-    return [headers, ...rows].map(row => row.map((value, index) => value + ' '.repeat(widths[index] - stringWidth(value))).join('  ').trimEnd()).join('\n')
-  }
-  // Keep every field readable when a full table would wrap in a narrow terminal.
-  const labelWidth = Math.max(...headers.map(value => stringWidth(value)))
-  const indent = ' '.repeat(labelWidth + 2)
-  return rows.map(row => headers.map((header, index) => {
-    const lines = wrapCell(row[index], Math.max(2, columns - indent.length))
-    return `${header.padEnd(labelWidth)}: ${lines.join(`\n${indent}`)}`
-  }).join('\n')).join('\n\n')
-}
-
-function isMain() {
-  try { return Boolean(process.argv[1]) && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url }
-  catch { return false }
-}
-if (isMain()) {
-  const controller = new AbortController()
-  const abort = () => controller.abort(error('CANCELLED', 'Command cancelled'))
-  process.once('SIGINT', abort); process.once('SIGTERM', abort)
-  try {
-    const options = parseCli(process.argv.slice(2))
-    const result = await runCli(options, { signal: controller.signal, onPhase: message => console.error(message) })
-    console.log(options.help ? usage : options.json ? JSON.stringify(result) : formatResult(result))
-    if (!options.json) for (const warning of result.warnings ?? []) console.error(`${warning.source}: ${warning.message}`)
-  } catch (failure) {
-    console.error(JSON.stringify({ ok: false, code: failure.code ?? 'COMMAND_FAILED', message: failure.code === 'ESPTOOL_UNAVAILABLE' || failure.code === 'ARGUMENT' || failure.code?.startsWith('ERR_PARSE_ARGS') ? failure.message : 'Command failed; check device access, firmware compatibility, arguments and adapter dependencies' }))
-    process.exitCode = controller.signal.aborted ? 130 : 1
-  } finally { process.removeListener('SIGINT', abort); process.removeListener('SIGTERM', abort) }
-}

package/tests/test-cli-output.mjs

@@ -1,31 +0,0 @@
-// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
-// SPDX-License-Identifier: Apache-2.0
-import test from 'node:test'
-import assert from 'node:assert/strict'
-import stringWidth from 'string-width'
-import { formatResult } from '../src/cli.js'
-
-test('wide tables align columns by terminal cells with CJK, combining characters and emoji', () => {
-  const devices = ['COM3', '/dev/开发板0', '/dev/e\u0301-👩‍💻'].map((address, index) => ({ number: index + 1, interface: 'usb', address, status: 'unprobed', identity: { board: 'BOARD', firmwareVersion: 'v1' } }))
-  const text = formatResult({ devices }, { columns: 1000 })
-  assert.ok(!text.includes('\t') && !text.includes('\\t'))
-  const lines = text.split('\n')
-  assert.equal(lines.length, 4)
-  const column = (line, word) => stringWidth(line.slice(0, line.indexOf(word)))
-  assert.ok(lines.slice(1).every(line => column(line, 'unprobed') === column(lines[0], 'Status')))
-  assert.ok(lines.slice(1).every(line => column(line, 'BOARD') === column(lines[0], 'Board')))
-})
-
-test('narrow terminals wrap full identifiers without losing Unicode graphemes or data', () => {
-  const address = '/dev/serial/by-id/usb-' + '开发板👩‍💻e\u0301'.repeat(12)
-  const text = formatResult({ devices: [{ number: 1, interface: 'usj', address, status: 'unprobed', usb: { serialNumber: 'SERIAL-123' } }] }, { columns: 60 })
-  assert.ok(text.split('\n').every(line => stringWidth(line) <= 60))
-  const value = text.split('\n').slice(text.split('\n').findIndex(line => line.startsWith('Address'))).join('\n').split('\nStatus')[0]
-  assert.equal(value.replace(/^Address\s*: /, '').replace(/\n +/g, ''), address)
-  assert.ok(text.includes('USB serial : SERIAL-123'))
-})
-
-test('empty discovery is explicit and non-inventory results keep their JSON format', () => {
-  assert.equal(formatResult({ devices: [] }), 'No devices found.')
-  assert.equal(formatResult({ ok: true }), JSON.stringify({ ok: true }, null, 2))
-})

package/tests/test-cli-ports.mjs

@@ -1,50 +0,0 @@
-// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
-// SPDX-License-Identifier: Apache-2.0
-import test from 'node:test'
-import assert from 'node:assert/strict'
-import { filterSerialPorts, inventory } from '../src/node_inventory.js'
-import { parseCli, runCli } from '../src/cli.js'
-
-const names = (ports, platform, allPorts = false) => filterSerialPorts(ports, { platform, allPorts }).map(port => port.path)
-
-test('Linux USB candidates survive missing descriptors and unrecognized vendors; native ports are opt-in', () => {
-  const ports = ['/dev/ttyACM0', '/dev/ttyUSB3', '/dev/ttyXRUSB0', '/dev/ttyS0', '/dev/ttyAMA0', '/dev/ttyTHS1', '/dev/rfcomm0', '/dev/tty0', '/dev/console', '/dev/pts/1', 'COM3'].map(path => ({ path }))
-  ports.push({ path: '/dev/customDriver0', vendorId: 0x9999 }, { path: '/dev/another0', hwid: 'USB VID:PID=9999:0001' })
-  assert.deepEqual(names(ports, 'linux'), ['/dev/ttyACM0', '/dev/ttyUSB3', '/dev/ttyXRUSB0', '/dev/customDriver0', '/dev/another0'])
-  assert.deepEqual(names(ports, 'linux', true), [...ports.slice(0, 7), ...ports.slice(11)].map(port => port.path))
-})
-
-test('Windows COM10+ and extended handles are accepted; native and virtual COM ports require all-ports', () => {
-  const ports = [{ path: 'COM3', vendorId: 0x303a }, { path: 'COM10', vendorId: 0x9999 }, { path: '\\\\.\\COM256', hwid: 'USB VID:PID=9999:0001' }, { path: 'com10', vendorId: 0x9999 }, { path: 'COM1' }, { path: 'COM7', hwid: 'BTHENUM' }, ...['COM0', 'COM-1', 'LPT1', '/dev/ttyUSB0', 'COM3\n'].map(path => ({ path, vendorId: 0x303a }))]
-  assert.deepEqual(names(ports, 'win32'), ['COM3', 'COM10', '\\\\.\\COM256'])
-  assert.deepEqual(names(ports, 'win32', true), ['COM3', 'COM10', '\\\\.\\COM256', 'COM1', 'COM7'])
-})
-
-test('macOS prefers callout endpoints without merging separate USB interfaces', () => {
-  const paths = ['/dev/tty.usbmodem101', '/dev/cu.usbmodem101', '/dev/cu.usbmodem102', '/dev/cu.usbserial-A', '/dev/cu.wchusbserial42', '/dev/cu.SLAB_USBtoUART', '/dev/cu.Bluetooth-Incoming-Port', '/dev/cu.debug-console', '/dev/tty.usbserial-B']
-  const ports = paths.map(path => ({ path }))
-  ports.push({ path: '/dev/cu.vendor device', vendorId: 0x9999 }, { path: '/dev/ttyACM0', vendorId: 0x303a })
-  const expected = [...paths.slice(1, 6), paths[8], '/dev/cu.vendor device']
-  assert.deepEqual(names(ports, 'darwin'), expected)
-  assert.deepEqual(names(ports, 'darwin', true), [...paths.slice(1), '/dev/cu.vendor device'])
-})
-
-test('inspect all-ports reaches passive enumeration and default query remains inspect', async () => {
-  assert.equal(parseCli([]).command, 'inspect')
-  assert.equal(parseCli(['inspect']).allPorts, false)
-  const options = parseCli(['inspect', '--all-ports', '--interface', 'serial'])
-  const result = await runCli(options, { platform: 'linux', inventory, async listSerial() { return [{ path: '/dev/ttyS0' }, { path: '/dev/ttyUSB0' }] }, createDevice() { throw new Error('Opened passive port') } })
-  assert.equal(result.devices.length, 2)
-  assert.throws(() => parseCli(['configure', '--port', 'COM3', '--forget-wifi', '--all-ports']))
-})
-
-test('explicit ports bypass enumeration policy, including UARTs and stable aliases', async () => {
-  for (const path of ['/dev/ttyS0', '/dev/serial/by-id/usb-board', '/dev/tty.vendor', 'COM1']) {
-    let opened
-    await runCli(parseCli(['inspect', '--port', path]), {
-      inventory() { throw new Error('Explicit target invoked discovery') }, transportFor: row => row,
-      createDevice({ transport }) { return { async connect() { opened = transport.address }, async inspect() { return {} }, async disconnect() {} } },
-    })
-    assert.equal(opened, path)
-  }
-})

package/tests/test-cli.mjs

@@ -1,98 +0,0 @@
-// SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
-// SPDX-License-Identifier: Apache-2.0
-import { test } from 'node:test'
-import assert from 'node:assert/strict'
-import { inventory, serialEntry } from '../src/node_inventory.js'
-import { parseCli, runCli, formatResult } from '../src/cli.js'
-const identity = { deviceId: 'abcdef123456', board: 'BOARD', firmwareVersion: 'v1', hostname: 'esp-vision-board' }
-const ports = [{ path: '/dev/ttyACM0', vendorId: 0x303a, productId: 0x1001, serialNumber: 'abc' }, { path: '/dev/ttyUSB0', vendorId: 0x10c4, productId: 0xea60 }, { path: '/dev/ttyACM1', vendorId: 0x303a, productId: 0x4003, product: 'ESP-VISION BOARD' }, { path: '/dev/ttyS0' }]
-const advertisement = { ...identity, addresses: ['192.168.1.7'], port: 3232, evMuxVersion: 4 }
-const deps = { platform: 'linux', async listSerial() { return ports }, async listNetwork() { return [advertisement] } }
-test('one inspect command supports Windows, Linux, macOS paths and strict command options', () => {
-  for (const serial of ['COM3', '/dev/ttyACM0', '/dev/cu.usbserial']) assert.equal(parseCli(['inspect', '--port', serial]).endpoint.address, serial)
-  assert.equal(parseCli(['inspect', '--tcp', '[::1]:3232']).endpoint.host, '::1')
-  for (const args of [['discover'], ['info'], ['inspect', '--tcp', 'tcp://user:pass@host'], ['inspect', '--port', 'a', '--tcp', 'b'], ['inspect', '--fields', 'network'], ['control', '--port', 'a', '--action', 'reset'], ['configure', '--port', 'a', '--ssid', 'x', '--forget-wifi'], ['firmware','update','--catalog','x','--board','BOARD','--current-version','v1']]) assert.throws(() => parseCli(args))
-})
-test('passive inventory never creates a session, keeps unidentified ports and numbers all results', async () => {
-  const result = await inventory({}, { ...deps, createDevice() { throw new Error('Passive enumeration opened a device') } })
-  assert.equal(result.devices.length, 4)
-  assert.equal(result.devices[0].status, 'advertised')
-  assert.deepEqual(result.devices.map(row => row.number), [1, 2, 3, 4])
-  const serial = result.devices.filter(row => row.interface !== 'tcp')
-  assert.ok(serial.every(row => row.identity === null && row.status === 'unprobed'))
-  assert.deepEqual(new Set(serial.map(row => row.interface)), new Set(['usj', 'usb', 'uart']))
-})
-test('USB product names are descriptor hints, never board identity or proof of firmware', () => {
-  const row = serialEntry(ports[2]); assert.equal(row.interface, 'usb'); assert.equal(row.identity, null)
-  assert.equal(serialEntry({ path: 'COM7', vendorId: 0x9999, product: 'Unknown ROM' }).interface, 'serial')
-})
-test('interface filters avoid unrelated discovery providers', async () => {
-  const serial = await inventory({ interfaces: ['uart'] }, { ...deps, listNetwork() { throw new Error('Unexpected LAN access') } })
-  assert.equal(serial.devices.length, 1); assert.deepEqual(serial.warnings, [])
-  const tcp = await inventory({ interfaces: ['tcp'] }, { ...deps, listSerial() { throw new Error('Unexpected serial access') } })
-  assert.equal(tcp.devices.length, 1); assert.deepEqual(tcp.warnings, [])
-})
-test('active probe groups one board across USB/TCP and retains failed ports at the end', async () => {
-  let disconnects = 0
-  const result = await inventory({ probe: true }, { ...deps, transportFor: row => row,
-    createDevice({ transport }) { return { async connect() { if (transport.address === '/dev/ttyACM0') throw Object.assign(new Error('busy'), { code: 'PORT_BUSY' }); return { identity } }, async inspect() { return { identity } }, async disconnect() { disconnects++ } } } })
-  assert.equal(disconnects, 4)
-  assert.ok(result.devices.slice(0, 3).every(row => row.group === 1 && row.status === 'identified'))
-  assert.equal(result.devices.at(-1).address, '/dev/ttyACM0'); assert.equal(result.devices.at(-1).error.code, 'PORT_BUSY')
-})
-test('partial discovery failure preserves valid results and empty successful discovery is valid', async () => {
-  const result = await inventory({}, { ...deps, async listNetwork() { throw new Error('missing mDNS') } })
-  assert.equal(result.sourcesAvailable, 1); assert.equal(result.devices.length, 3); assert.equal(result.warnings[0].source, 'tcp')
-  const empty = await runCli(parseCli(['inspect']), { inventory: async () => ({ devices: [], warnings: [{ source: 'tcp' }], sourcesAvailable: 1 }) })
-  assert.deepEqual(empty.devices, [])
-})
-test('targeted inspection calls only Core facade with selected fields and always disconnects', async () => {
-  const calls = []
-  const result = await runCli(parseCli(['inspect','--port','COM3','--fields','identity,capabilities']), { transportFor: row => row, createDevice() { return { async connect(options) { calls.push(options.role) }, async inspect(request) { calls.push(request.fields); return { identity } }, async disconnect() { calls.push('disconnect') } } } })
-  assert.deepEqual(result.identity, identity); assert.deepEqual(calls, ['unknown', ['identity','capabilities'], 'disconnect'])
-})
-test('selection resolves the same numbered enumeration snapshot, with discovered identity check', async () => {
-  let expected
-  await runCli(parseCli(['inspect','--select','1']), { inventory: async () => ({ devices: [{ number: 1, interface: 'tcp', advertisement }], warnings: [], sourcesAvailable: 1 }), transportFor: row => row, createDevice() { return { async connect(request) { expected = request.expectedDevice }, async inspect() { return {} }, async disconnect() {} } } })
-  assert.equal(expected, advertisement)
-})
-test('configure keeps Wi-Fi password out of results and forwards it only to configure', async () => {
-  let patch, closed = false
-  const result = await runCli(parseCli(['configure','--port','COM3','--ssid','WIFI','--password-stdin']), { transportFor: row => row, readPassword: async () => 'secret', createDevice() { return { async connect() {}, async configure(request) { patch = request.network }, async disconnect() { closed = true } } } })
-  assert.equal(patch.credentials.password, 'secret'); assert.deepEqual(result, { ok: true }); assert.equal(closed, true)
-})
-test('failed device operation still releases transport and session', async () => {
-  let closed = false
-  await assert.rejects(runCli(parseCli(['inspect','--tcp','localhost']), { transportFor: row => row, createDevice() { return { async connect() {}, async inspect() { throw new Error('failed') }, async disconnect() { closed = true } } } }), /failed/)
-  assert.equal(closed, true)
-})
-test('firmware CLI checks catalog/version then updates through the existing facade', async () => {
-  const calls = [], selected = { board: 'BOARD', version: 'v2' }
-  const result = await runCli(parseCli(['firmware','update','--catalog','catalog.json','--board','BOARD','--current-version','v1','--version','v2','--port','COM3']), { readFile: async () => '{"schemaVersion":1,"releases":[]}', openLoader() {}, createDevice() { return { firmware: { async check(request) { calls.push(request.version); return { release: selected } }, async update(request) { assert.equal(request.release, selected); return { verified: true } } }, async disconnect() { calls.push('disconnect') } } } })
-  assert.equal(result.verified, true); assert.deepEqual(calls, ['v2', 'disconnect'])
-})
-test('terminal output escapes control characters in device-provided data', () => {
-  const text = formatResult({ devices: [{ number: 1, address: 'COM3\x1b[31m', identity: { board: 'BOARD\nBAD' } }] })
-  assert.ok(!text.includes('\x1b')); assert.ok(text.includes('BOARD?BAD'))
-})
-
-test('cancelled active enumeration still releases the probed session', async () => {
-  const controller = new AbortController(); let closed = false
-  await assert.rejects(inventory({ probe: true, signal: controller.signal, interfaces: ['usj'] }, { ...deps, transportFor: row => row, createDevice() { return { async connect() { controller.abort(new Error('cancelled')); throw controller.signal.reason }, async disconnect() { closed = true } } } }), /cancelled/)
-  assert.equal(closed, true)
-})
-
-test('control passes the requested action and reset mode to Core without alias commands', async () => {
-  let request
-  const result = await runCli(parseCli(['control', '--port', 'COM3', '--action', 'reset', '--mode', 'soft']), { transportFor: row => row, createDevice() { return { async connect() {}, async control(value) { request = value; return { ok: true } }, async disconnect() {} } } })
-  assert.equal(result.ok, true); assert.equal(request.action, 'reset'); assert.equal(request.mode, 'soft')
-})
-
-test('normal firmware commands need neither a catalog nor a user loader module', async () => {
-  const options = parseCli(['firmware', 'update', '--port', 'COM3', '--version', 'new', '--board', 'BOARD'])
-  let loaderPort, request
-  await runCli(options, { transportFor: row => row, openLoader: ({ port }) => { loaderPort = port; return {} }, createDevice() { return { firmware: { async check(value) { request = value; return { release: { version: 'new' } } }, async update(value) { await value.openLoader({}); return { verified: true } } }, async disconnect() {} } } })
-  assert.equal(request.catalog, undefined); assert.equal(loaderPort, 'COM3')
-  assert.throws(() => parseCli(['firmware', 'update', '--port', 'COM3', '--version', 'new', '--loader', 'user.mjs']))
-  assert.throws(() => parseCli(['inspect', '--serial', 'COM3']))
-})