@esp-vision/device-core 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,9 +1,23 @@
 # Changelog
 
-## Unreleased
+## 0.1.1
+
+### Fixed
+
+- Expose `tcpTransport` and `serialTransport` through `@esp-vision/device-core/node`.
+- Include unit tests, hardware checks, fixtures and npm script targets in the tarball. Fail when no unit tests are found; validate imports, discovery and runnable checks from an isolated installed package.
+- Clarify `device.discover()` versus the provider's `list()` contract and document the shipped Node adapters and installed test commands.
+
+## 0.1.0 — Initial public release
 
 ### Added
 
+- Added browser-safe and optional Node LAN discovery interfaces, TTL-aware DNS-SD collection, and selection-time device identity validation before EV-MUX acquisition.
+
+- Standalone, UI-independent EV-MUX v4 sessions, strict ownership/epoch filtering, framed REPL, files, execution, Wi-Fi controls and device-action contracts.
+- Verified firmware-flash adapter with injected ROM loader, image/security/partition checks, complete readback and masked P4 download-latch reset.
+- Public npm metadata, protected default-branch publishing, isolated tarball checks and verified/idempotent release retries. The package has no Agent/IDE runtime dependency or bundle; the official firmware index uses a small TOML parser, and Node discovery optionally uses multicast-dns.
+
 - Default official firmware discovery reads dl.espressif.com config and per-version metadata; legacy unqualified releases remain visible without enabling unsafe writes. CLI uses --port and a built-in esptool process adapter, removing the user-supplied JavaScript loader requirement.
 
 - Ship `esp-vision-device` management CLI: unified `inspect` passive/probed wired/LAN queries matching the SDK method name, platform-aware USB serial filtering with `--all-ports` for native UART/Bluetooth, numbered/grouped endpoints, strict configuration/control and catalog/version firmware commands. Reuse Core facade and one cross-platform Python serial/TCP adapter in both CLI and hardware checks.
@@ -23,26 +37,14 @@
 
 ### Fixed
 
+- Preserve split mDNS address announcements during cache flush, reclaim expired cache entries, bound packet retention, and close discovery sockets when cancellation occurs during setup.
+- Soft reset requires a newer ready epoch and a real REPL barrier within one deadline; caller cancellation reaches all stages and device-action adapters.
+- Bounded file reads reject incomplete/changing content; serial startup drain, TCP frame deadlines and keepalive recovery follow the v4 contract.
+
 - Align discovery output by Unicode display width instead of tabs; fall back to aligned, wrapped device blocks on narrow terminals without truncating identifiers.
 
 - Generate script completion inside the executing statement so `input()` receives only user input; retain output arriving in the same frame as completion.
 - Return binary image results correlated to the requesting sequence instead of a shared last-image slot. LCD capture uses the dedicated `debug.capture_screen` capability and never falls back to the camera; this refactor does not implement the planned high-throughput binary firmware protocol.
 - Clean up subscriptions, pending work and transports on connection failure or session loss, and isolate event-listener exceptions from protocol delivery.
 
-## 0.1.0 — Initial public release
-
-### Added
-
-- Added browser-safe and optional Node LAN discovery interfaces, TTL-aware DNS-SD collection, and selection-time device identity validation before EV-MUX acquisition.
-
-- Standalone, UI-independent EV-MUX v4 sessions, strict ownership/epoch filtering, framed REPL, files, execution, Wi-Fi controls and device-action contracts.
-- Verified firmware-flash adapter with injected ROM loader, image/security/partition checks, complete readback and masked P4 download-latch reset.
-- Public npm metadata, protected default-branch publishing, isolated tarball checks and verified/idempotent release retries. The package has no Agent/IDE runtime dependency or bundle; the official firmware index uses a small TOML parser, and Node discovery optionally uses multicast-dns.
-
-### Fixed
-
-- Preserve split mDNS address announcements during cache flush, reclaim expired cache entries, bound packet retention, and close discovery sockets when cancellation occurs during setup.
-- Soft reset requires a newer ready epoch and a real REPL barrier within one deadline; caller cancellation reaches all stages and device-action adapters.
-- Bounded file reads reject incomplete/changing content; serial startup drain, TCP frame deadlines and keepalive recovery follow the v4 contract.
-
 The earlier v3 extraction existed only inside repository development history; it was not an npm release of this package. Version 0.1.0 is the first public v4-only package.

package/README.md

@@ -19,10 +19,10 @@
 | Visibility | Public; installation needs no npm login |
 | Source location | `host/device-core` in the ESP-VISION firmware repository |
 
-The npm page and installation become available only after the first publication succeeds. CI authenticates with the protected `NPM_PUBLISH_TOKEN` and verifies that `npm whoami` returns `esp-vision` before publishing. Tokens are not part of this package or its documentation.
+The `/node` export and bundled checks below require 0.1.1, the next patch release prepared by this source tree; 0.1.0 remains the published baseline until the release pipeline succeeds. CI authenticates with the protected `NPM_PUBLISH_TOKEN` and verifies that `npm whoami` returns `esp-vision` before publishing. Tokens are not part of this package or its documentation.
 
 ```sh
-npm install --save-exact @esp-vision/device-core@0.1.0 --registry=https://registry.npmjs.org/
+npm install --save-exact @esp-vision/device-core@0.1.1 --registry=https://registry.npmjs.org/
 ```
 
 EV-MUX v4 firmware is required. A v3 hello is rejected with `VERSION_MISMATCH`; applications should ask the user to update firmware. Core has no runtime dependency on the IDE, Agent, DOM or Node serial libraries. The host supplies the physical byte transport and discovery adapter; Core owns protocol parsing, session negotiation, REPL coordination and device operations.
@@ -41,7 +41,7 @@ Documentation source lives in this repository under `docs/en/device-core/` and `
 The npm package installs `esp-vision-device`. `inspect` combines passive wired/LAN enumeration and targeted queries. By default it lists USB serial candidates; `--all-ports` also includes native UART/Bluetooth ports. Explicit `--port` bypasses discovery filtering; `configure`, `control`, and `firmware check/update` cover management. See the [CLI guide](https://docs.espressif.com/projects/esp-vision/en/latest/esp32p4/device-core/cli.html) ([中文](https://docs.espressif.com/projects/esp-vision/zh_CN/latest/esp32p4/device-core/cli.html)).
 
 ```sh
-npm install -g @esp-vision/device-core@0.1.0
+npm install -g @esp-vision/device-core@0.1.1
 esp-vision-device inspect
 esp-vision-device inspect --all-ports
 esp-vision-device inspect --interface usj,usb --probe --json
@@ -49,7 +49,7 @@ esp-vision-device inspect --port COM3 --fields identity,capabilities
 esp-vision-device inspect --tcp 192.168.1.100:3232 --fields network,storage --json
 ```
 
-Wired access/enumeration requires Python with pyserial (`--python` overrides the interpreter); LAN discovery uses optional `multicast-dns`, normally installed by npm. Windows/Linux/macOS paths are accepted. Passive enumeration never opens a serial port; `--probe` and targeted queries acquire a session and may interrupt Python. Unidentified ports, ROM candidates and USB-to-UART adapters remain numbered and visible. Board names are unknown until firmware identification; USB descriptors are hints only. Firmware versions are fetched automatically from dl.espressif.com. Firmware flashing uses the built-in serial adapter with separately installed Python esptool>=5.3,<6; no user loader module is required. Historical releases without qualified update metadata remain listed but cannot be installed by this flow. Installation becomes available after first npm publication.
+Wired access/enumeration requires Python with pyserial (`--python` overrides the interpreter); LAN discovery uses optional `multicast-dns`, normally installed by npm. Windows/Linux/macOS paths are accepted. Passive enumeration never opens a serial port; `--probe` and targeted queries acquire a session and may interrupt Python. Unidentified ports, ROM candidates and USB-to-UART adapters remain numbered and visible. Board names are unknown until firmware identification; USB descriptors are hints only. Firmware versions are fetched automatically from dl.espressif.com. Firmware flashing uses the built-in serial adapter with separately installed Python esptool>=5.3,<6; no user loader module is required. Historical releases without qualified update metadata remain listed but cannot be installed by this flow. Check the registry version before installing a newly prepared release.
 
 ## Public device API
 
@@ -110,14 +110,39 @@ try {
 }
 ```
 
+### Official Node adapters
+
+The Node-only `@esp-vision/device-core/node` subpath exports `tcpTransport({ host, port })` and `serialTransport({ serial, python })`. Constructors are passive; Core opens/closes the link during `connect()`/`disconnect()`. Serial needs pyserial in the selected Python interpreter, and uses role `usj`, `usb` or `uart` for the actual interface. The root/browser entry points do not load Node networking/process modules.
+
+```js
+import { createDevice } from '@esp-vision/device-core';
+import { tcpTransport, serialTransport } from '@esp-vision/device-core/node';
+
+const tcpDevice = createDevice({ transport: tcpTransport({ host: '192.168.1.100', port: 3232 }) });
+const usbDevice = createDevice({ transport: serialTransport({ serial: '/dev/ttyACM0', python: 'python3' }) });
+// Connect only the selected device, and always disconnect() in finally.
+```
+
 A discovery-only instance can receive a transport later:
 
 ```js
-const [selected] = await device.discover({ timeout: 3000 });
-await device.connect({ transport: tcpAdapter, role: 'tcp', expectedDevice: selected });
+import { createDevice } from '@esp-vision/device-core';
+import { tcpTransport } from '@esp-vision/device-core/node';
+import { createNodeDiscovery } from '@esp-vision/device-core/discovery/node';
+
+const provider = createNodeDiscovery();
+const device = createDevice({ discovery: provider });
+const selected = (await device.discover({ timeout: 3000 })).find(item => item.compatible && item.addresses.length);
+if (!selected) throw new Error('No compatible device found');
+try {
+  await device.connect({ transport: tcpTransport({ host: selected.addresses[0], port: selected.port }), role: 'tcp', expectedDevice: selected });
+  console.log(await device.inspect({ fields: ['identity'] }));
+} finally { await device.disconnect(); }
 ```
 
-Opening `tcpAdapter` from the selected address/bridge URL remains the host's responsibility. Supported query fields are `identity`, `capabilities`, `runtime`, `network` and `storage`. The default is identity/capabilities/runtime; `inspect` reads only the requested fields and does not change configuration. Network/storage queries require the corresponding firmware capabilities. `connect()` returns that default inspection result after negotiation.
+Application discovery is `device.discover()`. `createNodeDiscovery()` and `createBridgeDiscovery()` return providers whose adapter contract is `list({ timeout, signal })`; they do not expose `discover()`. Inject a provider into `createDevice({ discovery: provider })` rather than calling `provider.discover()`. `list()` is the lower-level integration method, not another device API.
+
+Supported query fields are `identity`, `capabilities`, `runtime`, `network` and `storage`. The default is identity/capabilities/runtime; `inspect` reads only the requested fields and does not change configuration. Network/storage queries require the corresponding firmware capabilities. `connect()` returns that default inspection result after negotiation.
 
 ### Events
 
@@ -284,14 +309,24 @@ The package includes library source, schemas, license and documentation, with no
 
 ## Hardware acceptance
 
-Run the checked-out SDK against one idle device using Node.js 22. These checks use the public `createDevice()` API and release the session and transport afterwards. The default check reads identity/capabilities/runtime and executes a short `print()` without creating a device file. Connecting negotiates the REPL, so use a device whose running Python application may safely be interrupted. The check does not configure Wi-Fi, reset the board or erase storage.
+The package ships its unit suite and hardware runner. From your application directory, target the installed dependency explicitly:
+
+```sh
+npm --prefix node_modules/@esp-vision/device-core test
+npm --prefix node_modules/@esp-vision/device-core run test:hardware -- --help
+npm --prefix node_modules/@esp-vision/device-core run test:hardware -- --tcp 192.168.1.100:3232
+```
+
+Inside the source or installed package directory, use `npm test` and `npm run test:hardware -- ...`. Unit tests require no device. The runner explicitly enumerates tests and fails when the suite is absent or empty, rather than passing zero cases. The management CLI uses `--port`; the dedicated hardware runner uses `--serial`, as shown in its help.
+
+Run the source or installed SDK against one idle device using Node.js 22. These checks use the public `createDevice()` API and release the session and transport afterwards. The default check reads identity/capabilities/runtime and executes a short `print()` without creating a device file. Connecting negotiates the REPL, so use a device whose running Python application may safely be interrupted. The check does not configure Wi-Fi, reset the board or erase storage.
 
 ```sh
 npm run test:hardware -- --tcp 192.168.1.100:3232
-npm run test:hardware -- --port /dev/serial/by-id/YOUR_DEVICE --role usj
-npm run test:hardware -- --port /dev/serial/by-id/YOUR_USB_OTG_DEVICE --role usb --write
+npm run test:hardware -- --serial /dev/serial/by-id/YOUR_DEVICE --role usj
+npm run test:hardware -- --serial /dev/serial/by-id/YOUR_USB_OTG_DEVICE --role usb --write
 npm run test:hardware -- --tcp 192.168.1.100 --write --capture --timeout 90000
-npm run test:hardware -- --port /dev/serial/by-id/YOUR_DEVICE --role usj --checks all --frames 30 --output camera.jpg
+npm run test:hardware -- --serial /dev/serial/by-id/YOUR_DEVICE --role usj --checks all --frames 30 --output camera.jpg
 npm run test:hardware -- --tcp 192.168.1.100 --checks display --display-hold 2 --screen-output screen.jpg
 ```
 
@@ -303,7 +338,7 @@ These functional checks intentionally exercise sensor settings, image processing
 
 `--screen-output PATH` explicitly requests an LCD screenshot: it adds the `display` check when needed, draws red/green/blue/white bars with `ESP-VISION CI` text, validates backlight changes, captures that same display with `capture({ source: 'screen' })`, verifies JPEG completeness and panel dimensions, and writes the JPEG on the host before releasing the display. Missing LCD or screen capture support makes this explicit request fail instead of skip. Camera capture stays a separate source. Output images and logs should be placed under your project-local artifact directory when running this suite.
 
-TCP needs only Node.js. Serial additionally needs a Python interpreter with the optional [pyserial](https://pyserial.readthedocs.io/) dependency installed in your environment (`python3 -m pip install pyserial`, BSD-3-Clause; not vendored or included in the npm package). Select another interpreter with `--python /path/to/python`. The Apache-2.0-licensed serial adapter in `src/node_serial.py` is shared by the CLI and hardware runner; it enumerates ports without opening them, forwards bytes and configures RTS/DTR before opening; serial control-line behavior still depends on the board and OS driver. Hardware-check scripts and their tests stay in the source tree and are excluded from the published package.
+TCP needs only Node.js. Serial additionally needs a Python interpreter with the optional [pyserial](https://pyserial.readthedocs.io/) dependency installed in your environment (`python3 -m pip install pyserial`, BSD-3-Clause; not vendored or included in the npm package). Select another interpreter with `--python /path/to/python`. The Apache-2.0-licensed serial adapter in `src/node_serial.py` is shared by the CLI and hardware runner; it enumerates ports without opening them, forwards bytes and configures RTS/DTR before opening; serial control-line behavior still depends on the board and OS driver. The same hardware runner, unit tests and Python fixture ship in the source tree and npm tarball; no firmware/build outputs or device credentials are included.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esp-vision/device-core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Shared EV-MUX, framed REPL, device session, and action contracts for ESP Vision clients.",
   "type": "module",
   "exports": {
@@ -12,7 +12,8 @@
     "./bindings": "./src/device_bindings.js",
     "./firmware": "./src/firmware_flash.js",
     "./discovery": "./src/network_discovery.js",
-    "./discovery/node": "./src/network_discovery_node.js"
+    "./discovery/node": "./src/network_discovery_node.js",
+    "./node": "./src/node_transport.js"
   },
   "files": [
     "src/*.js",
@@ -21,11 +22,14 @@
     "CHANGELOG.md",
     "README.md",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "tests/*.mjs",
+    "tests/fixtures/*.py",
+    "scripts/*.mjs"
   ],
   "license": "Apache-2.0",
   "scripts": {
-    "test": "node --test tests/test-device-*.mjs tests/test-cli*.mjs tests/test-firmware-flash.mjs tests/test-network-discovery.mjs",
+    "test": "node scripts/run-tests.mjs",
     "check:schema": "node scripts/generate-action-schema.mjs --check",
     "schema:actions": "node scripts/generate-action-schema.mjs",
     "check:package": "node tests/check-package.mjs",

package/schemas/device-actions-v1.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "ESP Vision Device Actions",
-  "deviceCoreVersion": "0.1.0",
+  "deviceCoreVersion": "0.1.1",
   "schemaVersion": 1,
   "actions": [
     {

package/scripts/generate-action-schema.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/*
+ * SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert/strict'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import process from 'node:process'
+import {
+  DEVICE_ACTION_DESCRIPTORS,
+  DEVICE_ACTION_SCHEMA_VERSION,
+} from '../src/device_actions.js'
+
+const coreRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const corePackage = JSON.parse(await readFile(resolve(coreRoot, 'package.json'), 'utf8'))
+const outputPath = resolve(coreRoot, `schemas/device-actions-v${DEVICE_ACTION_SCHEMA_VERSION}.json`)
+const document = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  title: 'ESP Vision Device Actions',
+  deviceCoreVersion: corePackage.version,
+  schemaVersion: DEVICE_ACTION_SCHEMA_VERSION,
+  actions: DEVICE_ACTION_DESCRIPTORS,
+}
+const serialized = `${JSON.stringify(document, null, 2)}\n`
+
+if (process.argv.includes('--check')) {
+  assert.equal(await readFile(outputPath, 'utf8'), serialized, 'Device Action schema artifact is stale; regenerate it')
+  console.log(`Device Action Schema ${DEVICE_ACTION_SCHEMA_VERSION} is current`)
+} else {
+  await mkdir(dirname(outputPath), { recursive: true })
+  await writeFile(outputPath, serialized)
+  console.log(`Generated ${outputPath}`)
+}

package/scripts/release-npm.mjs

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const registry = 'https://registry.npmjs.org/'
+const dryRun = process.argv.includes('--dry-run')
+assert.ok(process.argv.slice(2).every(arg => arg === '--dry-run'), 'Unknown release argument')
+const manifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'))
+assert.equal(manifest.name, '@esp-vision/device-core')
+assert.match(manifest.version, /^\d+\.\d+\.\d+$/)
+assert.equal(manifest.publishConfig?.registry, registry)
+assert.equal(manifest.publishConfig?.access, 'public')
+assert.equal(manifest.license, 'Apache-2.0')
+if (!dryRun) {
+  assert.equal(process.env.CI_PIPELINE_SOURCE, 'push', 'Publish only from the merged default-branch pipeline')
+  assert.ok(process.env.CI_DEFAULT_BRANCH && process.env.CI_COMMIT_BRANCH === process.env.CI_DEFAULT_BRANCH,
+    'Publish only after manual merge to the default branch')
+  assert.equal(process.env.CI_COMMIT_REF_PROTECTED, 'true', 'Publishing requires a protected branch')
+  assert.ok(process.env.NPM_PUBLISH_TOKEN, 'Protected NPM_PUBLISH_TOKEN is missing')
+}
+const temporary = await mkdtemp(join(tmpdir(), 'esp-vision-core-release-'))
+try {
+  // Store an environment reference, never the token value, outside the package.
+  const config = join(temporary, 'npmrc')
+  await writeFile(config, `registry=${registry}\n//registry.npmjs.org/:_authToken=\${NPM_PUBLISH_TOKEN}\n`, { mode: 0o600 })
+  const env = dryRun ? { ...process.env } : { ...process.env, NPM_CONFIG_USERCONFIG: config }
+  function npm(args) {
+    const result = spawnSync('npm', args, { cwd: root, env, encoding: 'utf8' })
+    if (result.status !== 0) throw new Error(`npm ${args[0]} failed: ${result.stderr || result.error?.message}`)
+    return result.stdout
+  }
+  const [packed] = JSON.parse(npm(['pack', '--json', '--ignore-scripts', '--pack-destination', temporary]))
+  for (const required of ['LICENSE', 'NOTICE']) assert.ok(packed.files.some(({ path }) => path === required), `Missing ${required}`)
+  assert.ok(packed.files.every(({ path }) => /^(src\/|schemas\/|tests\/|scripts\/|package\.json$|README\.md$|LICENSE$|NOTICE$|CHANGELOG\.md$)/.test(path)),
+    'Only the standalone library may be published')
+  if (dryRun) {
+    npm(['publish', join(temporary, packed.filename), '--dry-run', '--ignore-scripts', '--access', 'public', '--registry', registry])
+    console.log(`Dry run: ${packed.name}@${packed.version}; ${packed.files.length} files; no registry write`)
+  } else {
+    const publisher = npm(['whoami', '--registry', registry]).trim()
+    assert.equal(publisher, 'esp-vision', 'Npm publisher account must be esp-vision')
+    console.log(`Npm publisher: ${publisher}`)
+    const url = new URL(encodeURIComponent(manifest.name), registry)
+    url.pathname += '/' + encodeURIComponent(manifest.version)
+    const response = await fetch(url, { signal: AbortSignal.timeout(15000) })
+    if (response.ok) {
+      const existing = await response.json()
+      assert.equal(existing.dist?.integrity, packed.integrity,
+        'This version already exists with different content; bump the package version')
+      console.log(`${packed.name}@${packed.version} already published with identical content; skipped`)
+    } else {
+      assert.equal(response.status, 404, 'Registry lookup failed; do not attempt publication')
+      npm(['publish', join(temporary, packed.filename), '--ignore-scripts', '--access', 'public', '--registry', registry])
+      const verified = JSON.parse(npm(['view', `${manifest.name}@${manifest.version}`, 'dist.integrity', '--json', '--registry', registry]))
+      assert.equal(verified, packed.integrity, 'Published tarball integrity mismatch')
+      console.log(`Published and verified ${packed.name}@${packed.version}`)
+    }
+  }
+} finally {
+  await rm(temporary, { recursive: true, force: true })
+}

package/scripts/run-tests.mjs

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import { readdir } from 'node:fs/promises'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import process from 'node:process'
+
+const root = fileURLToPath(new URL('../', import.meta.url))
+const tests = (await readdir(new URL('../tests/', import.meta.url)))
+  .filter(name => /^test-.*\.mjs$/.test(name)).sort()
+if (!tests.length) throw new Error('No Device Core unit tests found; the package is incomplete')
+const result = spawnSync(process.execPath, ['--test', ...process.argv.slice(2), ...tests.map(name => `tests/${name}`)], {
+  cwd: root, stdio: 'inherit',
+})
+if (result.error) throw result.error
+process.exitCode = result.status ?? 1

package/tests/check-package.mjs

@@ -0,0 +1,84 @@
+// SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import { execFileSync, spawnSync } from 'node:child_process'
+import { mkdtemp, readFile, rm, mkdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import process from 'node:process'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const manifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'))
+assert.equal(manifest.license, 'Apache-2.0')
+assert.match(await readFile(join(root, 'LICENSE'), 'utf8'), /Apache License[\s\S]*Version 2\.0/)
+const temporary = await mkdtemp(join(tmpdir(), 'esp-vision-device-core-package-'))
+try {
+  const [packed] = JSON.parse(execFileSync('npm', ['pack', '--json', '--ignore-scripts', '--pack-destination', temporary], { cwd: root, encoding: 'utf8' }))
+  assert.ok(packed.files.some(({ path }) => path === 'LICENSE'))
+  assert.ok(packed.files.some(({ path }) => path === 'NOTICE'))
+  assert.ok(packed.files.some(({ path }) => path === 'schemas/device-actions-v1.json'))
+  assert.ok(packed.files.every(({ path }) => /^(src\/|schemas\/|tests\/|scripts\/|package\.json$|README\.md$|LICENSE$|NOTICE$|CHANGELOG\.md$)/.test(path)), 'tarball must contain only the standalone library')
+  assert.ok(!packed.files.some(({ path }) => path.startsWith('docs/')), 'Documentation is published by the ESP-VISION documentation center')
+  assert.ok(!packed.files.some(({ path }) => path.includes('__pycache__') || path.endsWith('.pyc')), 'Never ship host Python bytecode')
+  const consumer = join(temporary, 'consumer')
+  await mkdir(consumer)
+  execFileSync('npm', ['install', '--offline', '--ignore-scripts', '--no-audit', '--no-fund', '--package-lock=false', join(temporary, packed.filename)], { cwd: consumer, stdio: 'pipe' })
+  const installed = join(consumer, 'node_modules/@esp-vision/device-core')
+  assert.equal(await readFile(join(installed, 'LICENSE'), 'utf8'), await readFile(join(root, 'LICENSE'), 'utf8'))
+  const notice = await readFile(join(installed, 'NOTICE'), 'utf8')
+  assert.ok(notice.includes('Copyright (c) 2024 Volodymyr Shymanskyy'))
+  assert.ok(notice.includes('Permission is hereby granted, free of charge'))
+  const entryPoints = Object.keys(manifest.exports).map(key => manifest.name + (key === '.' ? '' : key.slice(1)))
+  const script = `for (const name of ${JSON.stringify(entryPoints)}) {
+    const module = await import(name);
+    if (!Object.keys(module).length) throw new Error('Empty entry point: ' + name);
+  }
+  const api = await import('@esp-vision/device-core');
+  if (Object.keys(api).sort().join(',') !== 'createDevice') throw new Error('Root must expose only the application API');
+  const { DeviceSession } = await import('@esp-vision/device-core/session');
+  const { FirmwareFlashSession } = await import('@esp-vision/device-core/firmware');
+  const { tcpTransport, serialTransport } = await import('@esp-vision/device-core/node');
+  if (typeof tcpTransport !== 'function' || typeof serialTransport !== 'function') throw new Error('Missing public Node transports');
+  const { createNodeDiscovery } = await import('@esp-vision/device-core/discovery/node');
+  const { EventEmitter } = await import('node:events');
+  let queries = 0;
+  const provider = createNodeDiscovery({ createMdns() {
+    const mdns = new EventEmitter(); mdns.query = () => { queries++ }; mdns.destroy = () => {}; return mdns;
+  } });
+  const device = api.createDevice({ discovery: provider });
+  if (typeof provider.list !== 'function') throw new Error('Discovery providers must expose list()');
+  if ((await device.discover({ timeout: 50 })).length !== 0 || !queries) throw new Error('Device discovery did not call its provider');
+  // Constructors must be passive: these endpoints need not exist to create adapters.
+  api.createDevice({ transport: tcpTransport({ host: '127.0.0.1', port: 1 }) });
+  api.createDevice({ transport: serialTransport({ python: 'python3', serial: 'not-opened' }) });
+  if (typeof DeviceSession !== 'function' || typeof FirmwareFlashSession !== 'function') throw new Error('Missing host adapter APIs');`
+  execFileSync(process.execPath, ['--input-type=module', '-e', script], { cwd: consumer, stdio: 'pipe' })
+  assert.equal(manifest.bin['esp-vision-device'], './src/cli.js')
+  const help = execFileSync(process.execPath, [join(consumer, 'node_modules/@esp-vision/device-core/src/cli.js'), '--help'], { encoding: 'utf8' })
+  assert.ok(help.includes('esp-vision-device inspect'))
+  if (process.platform !== 'win32') {
+    const installedHelp = execFileSync(join(consumer, 'node_modules/.bin/esp-vision-device'), ['--help'], { encoding: 'utf8' })
+    assert.ok(installedHelp.includes('esp-vision-device inspect'), 'The installed npm command must execute through its symlink')
+  }
+  for (const required of ['src/node_serial.py', 'scripts/run-tests.mjs', 'tests/hardware-check.mjs', 'tests/device-checks.mjs', 'tests/fixtures/device-checks.py']) {
+    assert.ok(packed.files.some(({ path }) => path === required), `Missing installed check asset: ${required}`)
+  }
+  const unitOutput = execFileSync('npm', ['test'], { cwd: installed, encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 })
+  const unitCount = Number(/^# tests (\d+)$/m.exec(unitOutput)?.[1] ?? 0)
+  assert.ok(unitCount > 0, 'Installed npm test must execute a nonempty suite')
+  const hardwareHelp = execFileSync('npm', ['run', 'test:hardware', '--', '--help'], { cwd: installed, encoding: 'utf8' })
+  assert.ok(hardwareHelp.includes('--serial PATH'), 'Installed hardware runner must load and show its help')
+  // A damaged tarball must fail instead of reporting a successful zero-test run.
+  await rm(join(installed, 'tests'), { recursive: true })
+  await mkdir(join(installed, 'tests'))
+  const empty = spawnSync('npm', ['test'], { cwd: installed, encoding: 'utf8' })
+  assert.equal(empty.status, 1, 'An empty suite must fail closed')
+  assert.match(empty.stderr, /No Device Core unit tests found/)
+  await rm(join(installed, 'tests'), { recursive: true })
+  const missing = spawnSync('npm', ['test'], { cwd: installed, encoding: 'utf8' })
+  assert.equal(missing.status, 1, 'Missing tests must fail closed')
+  console.log(JSON.stringify({ package: packed.name, version: packed.version, entryPoints, unitCount, standalone: true }))
+} finally {
+  await rm(temporary, { recursive: true, force: true })
+}

package/tests/device-checks.mjs

@@ -0,0 +1,155 @@
+// SPDX-License-Identifier: Apache-2.0
+// Application-level HIL checks. All device I/O goes through createDevice's API.
+import { readFile, mkdir, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+export const DEVICE_CHECKS = Object.freeze(['identity', 'memory', 'camera', 'framesizes', 'pixformats', 'orientation', 'ipa_stats', 'snapshot_rate', 'preview', 'image_ops', 'display', 'display_stream'])
+const MARKER = '__EVDEVICECHECK__'
+const failure = (code, message) => Object.assign(new Error(message), { code })
+const unsupported = error => error?.code === 'UNSUPPORTED_OPERATION' || /ESP_ERR_NOT_SUPPORTED|ESP_ERR_NOT_FOUND|no module named|ENODEV/i.test(error?.message ?? '')
+function cancelled(signal) { if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : failure('CANCELLED', 'Device checks cancelled') }
+
+export function parseCheckResult(output, name) {
+  const lines = output.split(/\r?\n/).filter(line => line.startsWith(MARKER))
+  if (lines.length !== 1) throw failure('CHECK_REPORT_INVALID', 'Expected exactly one device check report')
+  let result
+  try { result = JSON.parse(lines[0].slice(MARKER.length)) } catch { throw failure('CHECK_REPORT_INVALID', 'Invalid device check JSON') }
+  if (!result || result.name !== name || !['PASS', 'SKIP', 'FAIL'].includes(result.status)) throw failure('CHECK_REPORT_INVALID', 'Unexpected device check result')
+  if (result.status === 'PASS' && (!result.data || typeof result.data !== 'object' || Array.isArray(result.data))) throw failure('CHECK_REPORT_INVALID', 'Missing device measurements')
+  if (result.status !== 'PASS' && (!result.error || typeof result.error.message !== 'string')) throw failure('CHECK_REPORT_INVALID', 'Missing device failure details')
+  return result
+}
+
+export async function saveJpeg(image, output) {
+  const data = image?.data
+  if (image?.mimeType !== 'image/jpeg' || !(data instanceof Uint8Array) || data.length < 4 || data[0] !== 255 || data[1] !== 216 || data.at(-2) !== 255 || data.at(-1) !== 217) throw failure('CAPTURE_INVALID', 'Capture is not a complete JPEG')
+  if (!(image.metadata?.width > 0 && image.metadata?.height > 0)) throw failure('CAPTURE_INVALID', 'Capture has no valid image dimensions')
+  if (output) { await mkdir(dirname(output), { recursive: true }); await writeFile(output, data) }
+  return { bytes: data.length, width: image.metadata.width, height: image.metadata.height }
+}
+
+function pause(milliseconds, signal) {
+  return new Promise((resolve, reject) => {
+    const cleanup = () => { clearTimeout(timer); signal?.removeEventListener('abort', abort) }
+    const abort = () => { cleanup(); reject(signal.reason ?? failure('CANCELLED', 'Device check cancelled')) }
+    const timer = setTimeout(() => { cleanup(); resolve() }, milliseconds)
+    signal?.addEventListener('abort', abort, { once: true })
+    if (signal?.aborted) abort()
+  })
+}
+
+export async function runDeviceChecks(device, options, { signal, nonce, report = value => console.log(JSON.stringify(value)) } = {}) {
+  const results = [], fixturePath = `/evhil_${nonce}.py`, namespace = `_evhil_${nonce}`
+  let ownsFixture = false, loaded = false, namespaceStarted = false, loadError = null
+  const parameters = { frames: options.frames, framesize: options.framesize, pixformat: options.pixformat, displayHold: options.displayHold, screenCapture: Boolean(options.screenOutput) }
+  const timeoutFor = name => 1000 * (name === 'display' ? 30 + options.displayHold * 3 : name === 'ipa_stats' ? options.frameTimeout + 40 : options.frameTimeout + Math.max(30, options.frames * (name === 'display_stream' ? 2 : 1)))
+  const execute = async (source, timeout = 10000, operationSignal = signal) => {
+    const result = await device.python.execute({ source, timeout, maxOutputChars: 16384, signal: operationSignal })
+    if (result.ok === false || result.outputTruncated) throw failure('PYTHON_CHECK', 'Device Python check did not complete')
+    return result.output
+  }
+  const load = async () => {
+    if (loaded) return
+    if (loadError) throw loadError
+    try {
+      const entries = await device.files.list({ path: '/', signal })
+      if (entries.some(entry => [fixturePath, `${fixturePath}.tmp`].includes(entry.path))) throw failure('TEST_PATH_EXISTS', 'Fixture path already exists')
+      const source = await readFile(new URL('./fixtures/device-checks.py', import.meta.url), 'utf8')
+      ownsFixture = true
+      await device.files.write({ path: fixturePath, data: source, overwrite: false, signal })
+      namespaceStarted = true
+      const loader = `with open(${JSON.stringify(fixturePath)}) as _fixture:\n exec(_fixture.read(),globals())`
+      await execute(`${namespace}={};exec(${JSON.stringify(loader)},${namespace})`)
+      loaded = true
+      await device.files.remove({ path: fixturePath, signal })
+    } catch (error) { loadError = error; throw error }
+  }
+  const invoke = async name => {
+    await load()
+    const output = await execute(`${namespace}['run_check'](${JSON.stringify(name)},${JSON.stringify(JSON.stringify(parameters))})`, timeoutFor(name))
+    return parseCheckResult(output, name)
+  }
+  const requirePass = result => {
+    if (result.status !== 'PASS') throw Object.assign(failure(result.status === 'SKIP' ? 'UNSUPPORTED_OPERATION' : 'DEVICE_CHECK_FAILED', result.error.message), { checkResult: result })
+    return result.data
+  }
+  const record = result => { results.push(result); report({ check: result.name, ...result, name: undefined }) }
+  try {
+    for (const name of options.checks) {
+      cancelled(signal)
+      const started = Date.now()
+      let result
+      try {
+        let data
+        if (name === 'identity') {
+          const info = await device.inspect({ fields: ['identity', 'capabilities', 'runtime'], signal })
+          if (!info.identity?.board || !info.identity.firmwareVersion || info.capabilities?.protocol?.evMuxVersion !== 4 || info.runtime?.vmReady !== true) throw failure('IDENTITY_INVALID', 'Expected a ready EV-MUX v4 firmware identity')
+          data = { identity: info.identity, features: info.capabilities.features, vmReady: info.runtime.vmReady }
+        } else if (name === 'camera') {
+          const image = await device.capture({ source: 'camera', format: 'jpeg', quality: options.quality, timeout: options.frameTimeout * 1000, signal })
+          data = await saveJpeg(image, options.output)
+          data.sensor = requirePass(await invoke('sensor_state'))
+        } else if (name === 'preview') {
+          let count = 0
+          const unsubscribe = device.on('preview', image => { if (image.data?.length) count++ })
+          try {
+            data = requirePass(await invoke(name))
+            await pause(2000, signal)
+            if (!count) throw failure('PREVIEW_EMPTY', 'No preview frame arrived')
+            data.received = count
+          } finally { unsubscribe() }
+        } else {
+          const response = await invoke(name)
+          if (name === 'ipa_stats' && response.status === 'SKIP') {
+            const info = await device.inspect({ fields: ['identity'], signal })
+            const board = (info.identity?.board ?? '').toUpperCase().replaceAll('-', '_')
+            if (['ESP32_P4X_EYE', 'ESP32_P4X_FUNCTION_EV_BOARD'].includes(board)) throw failure('IPA_REQUIRED', 'IPA statistics are required on this board')
+          }
+          data = requirePass(response)
+          if (name === 'display' && options.screenOutput) {
+            const image = await device.capture({ source: 'screen', format: 'jpeg', quality: options.quality, timeout: options.frameTimeout * 1000, signal })
+            const captured = await saveJpeg(image, options.screenOutput)
+            if (captured.width !== data.width || captured.height !== data.height) throw failure('SCREEN_SIZE_MISMATCH', 'LCD capture dimensions differ from display dimensions')
+            data.screen = captured
+          }
+        }
+        result = { name, status: 'PASS', data }
+      } catch (error) {
+        cancelled(signal)
+        const skip = unsupported(error) && !(name === 'display' && options.screenOutput)
+        result = { name, status: skip ? 'SKIP' : 'FAIL', error: { code: error.code ?? 'DEVICE_CHECK_FAILED', message: String(error.message ?? 'Device check failed').slice(0, 240) } }
+        if (error.code === 'WRITE_FAILED') {
+          try {
+            const status = await device.inspect({ fields: ['storage'], timeout: 3000, signal })
+            result.storage = Object.fromEntries(Object.entries(status.storage).map(([volume, state]) => [volume, { present: state.present, mounted: state.mounted, status: state.status, writable: state.writable, reason: state.reason }]))
+          } catch { /* Preserve the upload failure. */ }
+        }
+      } finally {
+        if (name === 'display' && loaded) {
+          try { await execute(`${namespace}['close_display']()`, 5000, AbortSignal.timeout(6000)) }
+          catch { result = { name, status: 'FAIL', error: { code: 'DISPLAY_CLEANUP_FAILED', message: 'Could not release the test display' } } }
+        }
+      }
+      result.seconds = (Date.now() - started) / 1000
+      record(result)
+    }
+  } finally {
+    const cleanupSignal = AbortSignal.timeout(10000)
+    let cleanupError
+    if (namespaceStarted) {
+      try { await execute(`if ${JSON.stringify(namespace)} in globals():\n ${namespace}.get('close_display',lambda:None)()\n del ${namespace}`, 5000, cleanupSignal) }
+      catch (error) { cleanupError = error }
+    }
+    if (ownsFixture) {
+      try {
+        const entries = await device.files.list({ path: '/', signal: cleanupSignal })
+        for (const entry of entries) if ([fixturePath, `${fixturePath}.tmp`].includes(entry.path)) await device.files.remove({ path: entry.path, signal: cleanupSignal })
+      } catch (error) { cleanupError ??= error }
+    }
+    if (cleanupError) record({ name: 'fixture-cleanup', status: 'FAIL', error: { code: 'FIXTURE_CLEANUP_FAILED', message: 'Could not clean up the hardware fixture', path: fixturePath } })
+  }
+  const summary = { passed: results.filter(result => result.status === 'PASS').length, failed: results.filter(result => result.status === 'FAIL').length, skipped: results.filter(result => result.status === 'SKIP').length }
+  report({ check: 'summary', ...summary })
+  if (summary.failed) throw Object.assign(failure('DEVICE_CHECKS_FAILED', 'One or more device checks failed'), { results })
+  return results
+}