@esp-vision/device-core 0.1.0 → 0.1.1

package/tests/fixtures/device-checks.py

@@ -0,0 +1,317 @@
+# SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+"""Device-side camera/LCD fixtures migrated from tools/ci/device_checks.py.
+
+All transport, ownership and cleanup are supplied by the public JS SDK.
+"""
+
+
+def framesizes(opts):
+    import sensor
+    sensor.reset()
+    sensor.set_pixformat(sensor.RGB565)
+    results = []
+    for name in ('QQVGA', 'QVGA', 'VGA'):
+        try:
+            sensor.set_framesize(getattr(sensor, name))
+            sensor.skip_frames(n=2)
+            img = sensor.snapshot()
+            results.append(dict(name=name, supported=True, width=img.width(), height=img.height(),
+                                reportedWidth=sensor.width(), reportedHeight=sensor.height()))
+        except Exception:
+            results.append(dict(name=name, supported=False))
+    working = [item for item in results if item['supported']]
+    assert working, 'no framesize produced a frame'
+    for item in working:
+        assert item['width'] == item['reportedWidth'] and item['height'] == item['reportedHeight'], 'frame size differs from sensor-reported size: ' + item['name']
+    return dict(results=results)
+
+
+def pixformats(opts):
+    import sensor
+    sensor.reset()
+    sensor.set_framesize(getattr(sensor, opts['framesize']))
+    results = []
+    for name, depth in (('RGB565', 2), ('GRAYSCALE', 1)):
+        try:
+            sensor.set_pixformat(getattr(sensor, name))
+            sensor.skip_frames(n=2)
+            img = sensor.snapshot()
+            results.append(dict(name=name, supported=True, width=img.width(), height=img.height(),
+                                actualBytes=img.size(), expectedBytes=img.width() * img.height() * depth))
+        except Exception:
+            results.append(dict(name=name, supported=False))
+    working = [item for item in results if item['supported']]
+    assert working, 'no pixel format produced a frame'
+    for item in working:
+        assert item['actualBytes'] == item['expectedBytes'], 'pixel buffer size mismatch: ' + item['name']
+    return dict(results=results)
+
+
+def orientation(opts):
+    import sensor
+    sensor.reset()
+    sensor.set_pixformat(getattr(sensor, opts['pixformat']))
+    sensor.set_framesize(getattr(sensor, opts['framesize']))
+    sensor.skip_frames(n=3)
+    sensor.set_hmirror(True)
+    sensor.set_vflip(True)
+    sensor.skip_frames(n=2)
+    img = sensor.snapshot()
+    mirrored = (int(sensor.get_hmirror()), int(sensor.get_vflip()))
+    sensor.set_hmirror(False)
+    sensor.set_vflip(False)
+    sensor.skip_frames(n=2)
+    sensor.snapshot()
+    assert mirrored == (1, 1), 'mirror or flip did not turn on'
+    assert not sensor.get_hmirror() and not sensor.get_vflip(), 'mirror or flip did not turn off'
+    return dict(width=img.width(), height=img.height(), mirrored=list(mirrored))
+
+
+def ipa_stats(opts):
+    import sensor
+    sensor.reset()
+    sensor.set_pixformat(getattr(sensor, opts['pixformat']))
+    sensor.set_framesize(getattr(sensor, opts['framesize']))
+    sensor.skip_frames(n=3)
+    import json
+    if not hasattr(sensor, 'get_ipa_stats'):
+        raise RuntimeError('ESP_ERR_NOT_SUPPORTED: IPA statistics API absent')
+    original = sensor.get_ipa()
+    if original is None:
+        raise RuntimeError('ESP_ERR_NOT_SUPPORTED: runtime IPA unavailable')
+
+    def uint(value, bits):
+        assert type(value) is int and 0 <= value < 1 << bits, 'invalid unsigned statistic'
+
+    def awb(value):
+        assert isinstance(value, dict), 'AWB must be a dictionary'
+        assert set(value) == set(('counted', 'sum_r', 'sum_g', 'sum_b')), 'AWB fields'
+        for number in value.values():
+            uint(number, 32)
+
+    def grid(value, validate):
+        assert isinstance(value, list) and len(value) == 5, 'grid X size'
+        for column in value:
+            assert isinstance(column, list) and len(column) == 5, 'grid Y size'
+            for cell in column:
+                validate(cell)
+
+    def validate(stats):
+        assert isinstance(stats, dict), 'statistics must be a dictionary'
+        keys = ('seq', 'flags', 'ae', 'awb', 'awb_subwin', 'hist', 'sharpen', 'af')
+        assert set(stats) == set(keys), 'statistics fields'
+        uint(stats['seq'], 64)
+        uint(stats['flags'], 6)
+        assert stats['flags'] != 0, 'no valid statistics blocks'
+        for name, flag in (('awb', 1), ('ae', 2), ('hist', 4), ('sharpen', 8), ('af', 16), ('awb_subwin', 32)):
+            assert (stats[name] is not None) == bool(stats['flags'] & flag), 'validity mismatch: ' + name
+        if stats['ae'] is not None:
+            grid(stats['ae'], lambda value: uint(value, 32))
+        if stats['awb'] is not None:
+            awb(stats['awb'])
+        if stats['awb_subwin'] is not None:
+            assert stats['awb'] is not None, 'subwindows without global AWB'
+            grid(stats['awb_subwin'], awb)
+        if stats['hist'] is not None:
+            assert isinstance(stats['hist'], list) and len(stats['hist']) == 16, 'histogram size'
+            for value in stats['hist']:
+                uint(value, 32)
+        if stats['sharpen'] is not None:
+            uint(stats['sharpen'], 8)
+        if stats['af'] is not None:
+            assert isinstance(stats['af'], list) and len(stats['af']) == 3, 'AF window count'
+            for window in stats['af']:
+                assert isinstance(window, dict), 'AF must be a dictionary'
+                assert set(window) == set(('definition', 'luminance')), 'AF fields'
+                uint(window['definition'], 32)
+                uint(window['luminance'], 32)
+
+    def sample():
+        for _ in range(5):
+            sensor.skip_frames(n=2)
+            stats = sensor.get_ipa_stats(timeout=200)
+            if stats is not None:
+                validate(stats)
+                return stats
+        raise RuntimeError('no IPA statistics after five reads')
+    sequences = []
+    flags = []
+    try:
+        sensor.set_ipa(True)
+        assert sensor.get_ipa() is True, 'IPA did not start'
+        for timeout in (-1, 0, 1001):
+            try:
+                sensor.get_ipa_stats(timeout=timeout)
+            except ValueError:
+                pass
+            else:
+                raise RuntimeError('invalid timeout accepted')
+        for _ in range(3):
+            stats = sample()
+            if sequences:
+                assert stats['seq'] > sequences[-1], 'stale statistics sequence'
+            sequences.append(stats['seq'])
+            flags.append(stats['flags'])
+        sensor.set_ipa(False)
+        assert sensor.get_ipa() is False, 'IPA did not stop'
+        sensor.snapshot()
+        try:
+            sensor.get_ipa_stats(timeout=200)
+        except OSError as exc:
+            assert 'ESP_ERR_INVALID_STATE' in str(exc), 'wrong disabled-IPA error'
+        else:
+            raise RuntimeError('statistics read accepted while IPA disabled')
+        sensor.set_ipa(True)
+        assert sensor.get_ipa() is True, 'IPA did not restart'
+        stats = sample()
+        restarted_seq = stats['seq']
+        sensor.snapshot()
+    finally:
+        sensor.set_ipa(original)
+    assert sensor.get_ipa() is original, 'IPA state was not restored'
+    return dict(seq=sequences, flags=flags, restarted_seq=restarted_seq)
+
+
+def snapshot_rate(opts):
+    import sensor
+    sensor.reset()
+    sensor.set_pixformat(getattr(sensor, opts['pixformat']))
+    sensor.set_framesize(getattr(sensor, opts['framesize']))
+    sensor.skip_frames(n=3)
+    import time
+    img = sensor.snapshot()
+    start = time.ticks_ms()
+    for _ in range(opts['frames']):
+        img = sensor.snapshot()
+    elapsed = time.ticks_diff(time.ticks_ms(), start)
+    assert elapsed > 0, 'implausible capture time'
+    return dict(width=img.width(), height=img.height(), elapsedMs=elapsed, frames=opts['frames'])
+
+
+def preview(opts):
+    import sensor
+    sensor.reset()
+    sensor.set_pixformat(getattr(sensor, opts['pixformat']))
+    sensor.set_framesize(getattr(sensor, opts['framesize']))
+    sensor.skip_frames(n=3)
+    for _ in range(opts['frames']):
+        sensor.snapshot().flush()
+    return dict(flushed=opts['frames'])
+
+
+def image_ops(opts):
+    import sensor
+    sensor.reset()
+    sensor.set_pixformat(getattr(sensor, opts['pixformat']))
+    sensor.set_framesize(getattr(sensor, opts['framesize']))
+    sensor.skip_frames(n=3)
+    img = sensor.snapshot()
+    width, height = (img.width(), img.height())
+    img.draw_rectangle(4, 4, 40, 30, color=(255, 0, 0), thickness=2)
+    img.draw_line(0, 0, width - 1, height - 1, color=(0, 255, 0), thickness=2)
+    img.draw_string(4, 40, 'CI', color=(255, 255, 255), scale=2)
+    half = img.copy(x_scale=0.5, y_scale=0.5)
+    mean = img.get_statistics().mean()
+    jpeg = img.compress(quality=60)
+    assert half.width() == width // 2 and half.height() == height // 2, 'incorrect half-scale image'
+    assert jpeg.size() > 0, 'empty compressed JPEG'
+    return dict(width=width, height=height, halfWidth=half.width(), halfHeight=half.height(), mean=mean, jpegBytes=jpeg.size())
+
+
+_lcd = None
+
+
+def close_display():
+    global _lcd
+    lcd, _lcd = _lcd, None
+    if lcd is not None:
+        lcd.deinit()
+
+
+def display(opts):
+    global _lcd
+    import display, image, time
+    close_display()
+    lcd = _lcd = display.Display(backlight=100)
+    try:
+        frame = image.Image(lcd.width(), lcd.height(), image.RGB565)
+        colors = ((255, 0, 0), (0, 255, 0), (0, 0, 255), (255, 255, 255))
+        bar = frame.width() // len(colors)
+        for index, color in enumerate(colors):
+            frame.draw_rectangle(index * bar, 0, bar, frame.height(), color=color, fill=True)
+        frame.draw_string(8, 8, 'ESP-VISION CI', color=(0, 0, 0), scale=2)
+        lcd.write(frame, fit=False)
+        time.sleep(opts['displayHold'])
+        lcd.backlight(40)
+        dimmed = lcd.backlight()
+        time.sleep(opts['displayHold'])
+        lcd.backlight(100)
+        time.sleep(opts['displayHold'])
+        assert dimmed == 40 and lcd.backlight() == 100, 'backlight did not follow requested levels'
+        return dict(width=lcd.width(), height=lcd.height(), dimmed=dimmed, restored=lcd.backlight())
+    finally:
+        if not opts.get('screenCapture'):
+            close_display()
+
+
+def display_stream(opts):
+    import sensor
+    sensor.reset()
+    sensor.set_pixformat(getattr(sensor, opts['pixformat']))
+    sensor.set_framesize(getattr(sensor, opts['framesize']))
+    sensor.skip_frames(n=3)
+    import display, time
+    lcd = display.Display(backlight=100)
+    try:
+        img = sensor.snapshot()
+        lcd.write(img)
+        start = time.ticks_ms()
+        for _ in range(max(10, opts['frames'] // 2)):
+            lcd.write(sensor.snapshot())
+        elapsed = time.ticks_diff(time.ticks_ms(), start)
+        lcd.clear()
+        assert elapsed > 0, 'implausible display stream time'
+        return dict(width=lcd.width(), height=lcd.height(), cameraWidth=img.width(), cameraHeight=img.height(), elapsedMs=elapsed, frames=max(10, opts['frames'] // 2))
+    finally:
+        lcd.deinit()
+
+
+
+def memory(opts):
+    import esp32
+    heaps = esp32.idf_heap_info(esp32.HEAP_DATA)
+    psram = esp32.idf_heap_info(1 << 10)  # ESP-IDF MALLOC_CAP_SPIRAM.
+    free = sum(item[1] for item in heaps)
+    assert free > 0, 'no heap left'
+    return dict(heapFree=free, heapLargest=max([item[2] for item in heaps] or [0]),
+                psramFree=sum(item[1] for item in psram),
+                psramLargest=max([item[2] for item in psram] or [0]))
+
+
+def sensor_state(opts):
+    import sensor
+    width, height = sensor.width(), sensor.height()
+    assert width > 0 and height > 0, 'sensor not ready after capture'
+    return dict(width=width, height=height, id=sensor.get_id(),
+                pixformat=sensor.get_pixformat(), hmirror=sensor.get_hmirror(),
+                vflip=sensor.get_vflip())
+
+
+def run_check(name, opts):
+    import json
+    if isinstance(opts, str):
+        opts = json.loads(opts)
+    functions = dict(memory=memory, sensor_state=sensor_state, framesizes=framesizes,
+                     pixformats=pixformats, orientation=orientation, ipa_stats=ipa_stats,
+                     snapshot_rate=snapshot_rate, preview=preview, image_ops=image_ops,
+                     display=display, display_stream=display_stream)
+    try:
+        data = functions[name](opts)
+        result = dict(name=name, status='PASS', data=data)
+    except Exception as exc:
+        message = str(exc)
+        unsupported = ('ESP_ERR_NOT_SUPPORTED', 'ESP_ERR_NOT_FOUND', 'no module named', 'ENODEV')
+        status = 'SKIP' if any(token.lower() in message.lower() for token in unsupported) else 'FAIL'
+        result = dict(name=name, status=status, error=dict(type=type(exc).__name__, message=message))
+    print('__EVDEVICECHECK__' + json.dumps(result))

package/tests/hardware-check.mjs

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: Apache-2.0
+import { randomBytes } from 'node:crypto'
+import { fileURLToPath } from 'node:url'
+import { resolve } from 'node:path'
+import { tcpTransport, serialTransport } from '../src/node_transport.js'
+export { tcpTransport, serialTransport } from '../src/node_transport.js'
+import { createDevice } from '../src/index.js'
+import { DEVICE_CHECKS, runDeviceChecks, saveJpeg } from './device-checks.mjs'
+
+export const usage = 'Usage: npm run test:hardware -- (--tcp HOST[:PORT] | --serial PATH) [--role usj|usb|uart] [--python PYTHON] [--write] [--capture] [--checks all|CSV] [--frames N] [--framesize QVGA] [--pixformat RGB565] [--quality 60] [--frame-timeout SECONDS] [--display-hold SECONDS] [--output CAMERA.jpg] [--screen-output LCD.jpg] [--timeout MILLISECONDS]'
+const fail = (code, message) => Object.assign(new Error(message), { code })
+
+export function parseArgs(args) {
+  const options = { timeout: 60000, write: false, capture: false, python: 'python3', frames: 30, framesize: 'QVGA', pixformat: 'RGB565', quality: 60, frameTimeout: 25, displayHold: 0 }
+  let explicitTimeout = false
+  for (let index = 0; index < args.length; index++) {
+    const option = args[index]
+    if (option === '--help') return { help: true }
+    if (option === '--write' || option === '--capture') { options[option.slice(2)] = true; continue }
+    if (!['--tcp', '--serial', '--role', '--python', '--timeout', '--checks', '--screen-output', '--output', '--frames', '--display-hold', '--framesize', '--pixformat', '--quality', '--frame-timeout'].includes(option)) throw fail('ARGUMENT', 'Unknown argument')
+    const value = args[++index]
+    if (!value || value.startsWith('--')) throw fail('ARGUMENT', 'Missing argument value')
+    const key = option.slice(2).replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase())
+    options[key] = value
+    if (key === 'timeout') explicitTimeout = true
+  }
+  if (Boolean(options.tcp) === Boolean(options.serial)) throw fail('ARGUMENT', 'Select exactly one transport')
+  if (options.checks) {
+    options.checks = options.checks === 'all' ? [...DEVICE_CHECKS] : [...new Set(options.checks.split(',').map(name => name.trim()))]
+    if (options.checks.some(name => !DEVICE_CHECKS.includes(name))) throw fail('ARGUMENT', 'Unknown device check')
+  } else options.checks = []
+  if (options.screenOutput && !options.checks.includes('display')) options.checks.push('display')
+  if (options.checks.length && !explicitTimeout) options.timeout = 600000
+  for (const key of ['frames', 'quality', 'frameTimeout', 'displayHold']) options[key] = Number(options[key])
+  if (!Number.isInteger(options.frames) || options.frames < 1 || options.frames > 1000) throw fail('ARGUMENT', 'Frames must be 1 to 1000')
+  if (!Number.isInteger(options.quality) || options.quality < 1 || options.quality > 100) throw fail('ARGUMENT', 'Quality must be 1 to 100')
+  if (!Number.isFinite(options.frameTimeout) || options.frameTimeout <= 0 || options.frameTimeout > 120) throw fail('ARGUMENT', 'Frame timeout must be positive and at most 120 seconds')
+  if (!Number.isFinite(options.displayHold) || options.displayHold < 0 || options.displayHold > 60) throw fail('ARGUMENT', 'Display hold must be 0 to 60 seconds')
+  if (![options.framesize, options.pixformat].every(value => /^[A-Z][A-Z0-9_]{0,30}$/.test(value))) throw fail('ARGUMENT', 'Sensor settings must be uppercase constant names')
+  if (options.output && !options.checks.includes('camera')) options.capture = true
+  options.timeout = Number(options.timeout)
+  if (!Number.isSafeInteger(options.timeout) || options.timeout < 1000 || options.timeout > 600000) throw fail('ARGUMENT', 'Timeout must be 1000 to 600000 milliseconds')
+  if (options.tcp) {
+    const match = /^(?:\[([0-9a-fA-F:]+)\]|([^\s:/]+))(?::([0-9]+))?$/.exec(options.tcp)
+    if (!match || /[@?#]/.test(options.tcp)) throw fail('ARGUMENT', 'Expected TCP host[:port] without credentials or URL')
+    options.host = match[1] ?? match[2]
+    options.port = Number(match[3] ?? 3232)
+    if (options.port < 1 || options.port > 65535) throw fail('ARGUMENT', 'Invalid TCP port')
+    if (options.role) throw fail('ARGUMENT', '--role only applies to serial')
+    options.role = 'tcp'
+  } else {
+    options.role ??= 'usj'
+    if (!['usj', 'usb', 'uart'].includes(options.role)) throw fail('ARGUMENT', 'Serial role must be usj, usb or uart')
+  }
+  return options
+}
+
+async function bounded(operation, milliseconds) {
+  let timer
+  try { return await Promise.race([operation(), new Promise((_resolve, reject) => { timer = setTimeout(() => reject(fail('CLEANUP_TIMEOUT', 'Cleanup timed out')), milliseconds) })]) }
+  finally { clearTimeout(timer) }
+}
+
+/** Uses only the public facade; injectable for deterministic non-hardware checks. */
+export async function checkHardware(options, { device = createDevice({ transport: options.tcp ? tcpTransport(options) : serialTransport(options) }), signal, report = value => console.log(JSON.stringify(value)), nonce = randomBytes(8).toString('hex') } = {}) {
+  const controller = new AbortController()
+  const abort = () => controller.abort(fail('CANCELLED', 'Hardware check cancelled'))
+  signal?.addEventListener('abort', abort, { once: true })
+  if (signal?.aborted) abort()
+  const timer = setTimeout(() => controller.abort(fail('TIMEOUT', 'Hardware check timed out')), options.timeout)
+  let error, ownedPath = null, writeStarted = false
+  const path = `/evhc_${nonce}.bin`
+  const cancelled = () => { if (controller.signal.aborted) throw controller.signal.reason }
+  try {
+    await device.connect({ role: options.role, timeout: Math.min(options.timeout, 30000), signal: controller.signal })
+    cancelled()
+    const status = await device.inspect({ fields: ['identity', 'capabilities', 'runtime'], signal: controller.signal })
+    // Only selected public identity fields are logged; never network credentials or Python output.
+    report({ check: 'inspect', ok: true, identity: { deviceId: status.identity?.deviceId ?? null, board: status.identity?.board ?? null, hostname: status.identity?.hostname ?? null } })
+    const marker = `EV_HARDWARE_${nonce}`
+    const execution = await device.python.execute({ source: `print('${marker}')`, timeout: 10000, maxOutputChars: 1024, signal: controller.signal })
+    if (!execution.ok || !execution.output.split(/\r?\n/).some(line => line.trim() === marker)) throw fail('PYTHON_CHECK', 'Python marker was not received')
+    report({ check: 'python', ok: true })
+    if (options.write) {
+      const entries = await device.files.list({ path: '/', signal: controller.signal })
+      if (entries.some(entry => entry.path === path || entry.path === `${path}.tmp`)) throw fail('TEST_PATH_EXISTS', 'Test path already exists; refusing to modify it')
+      ownedPath = path
+      const bytes = Uint8Array.from({ length: 1024 }, (_value, index) => (index * 73 + 29) & 255)
+      writeStarted = true
+      await device.files.write({ path, data: bytes, overwrite: false, signal: controller.signal })
+      const read = await device.files.read({ path, maxBytes: bytes.length, timeout: 15000, signal: controller.signal })
+      if (read.length !== bytes.length || !bytes.every((byte, index) => byte === read[index])) throw fail('READBACK_MISMATCH', 'File readback mismatch')
+      report({ check: 'write-read', ok: true, bytes: bytes.length })
+    }
+    if (options.capture && !options.checks.includes('camera')) {
+      const image = await device.capture({ source: 'camera', format: 'jpeg', quality: options.quality, timeout: options.frameTimeout * 1000, signal: controller.signal })
+      const captured = await saveJpeg(image, options.output)
+      report({ check: 'capture', ok: true, ...captured })
+    }
+    if (options.checks.length) await runDeviceChecks(device, options, { signal: controller.signal, nonce, report })
+    cancelled()
+  } catch (caught) { error = caught }
+  finally {
+    clearTimeout(timer)
+    signal?.removeEventListener('abort', abort)
+    if (ownedPath && writeStarted) {
+      try {
+        await bounded(async () => {
+          const cleanupSignal = AbortSignal.timeout(5000)
+          const entries = await device.files.list({ path: '/', signal: cleanupSignal })
+          for (const entry of entries) if ([ownedPath, `${ownedPath}.tmp`].includes(entry.path)) await device.files.remove({ path: entry.path, signal: cleanupSignal })
+        }, 6000)
+        report({ check: 'file-cleanup', ok: true })
+      } catch (caught) { report({ check: 'file-cleanup', ok: false, path: ownedPath }); error ??= caught }
+    }
+    try { await bounded(() => device.disconnect(), 10000) }
+    catch (caught) { error ??= caught }
+  }
+  if (error) throw error
+  return { ok: true }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const controller = new AbortController()
+  const cancel = () => controller.abort()
+  process.once('SIGINT', cancel)
+  process.once('SIGTERM', cancel)
+  try {
+    const options = parseArgs(process.argv.slice(2))
+    if (options.help) console.log(usage)
+    else await checkHardware(options, { signal: controller.signal })
+  } catch (error) {
+    const code = typeof error?.code === 'string' && /^[A-Z0-9_]+$/.test(error.code) ? error.code : 'HARDWARE_CHECK_FAILED'
+    console.error(JSON.stringify({ ok: false, code }))
+    process.exitCode = 1
+  } finally {
+    process.removeListener('SIGINT', cancel)
+    process.removeListener('SIGTERM', cancel)
+  }
+}

package/tests/test-cli-output.mjs

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

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

@@ -0,0 +1,98 @@
+// 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']))
+})