@esptool/mac 0.0.0-stage → 0.1.4

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# esptool.mac（@esptool/mac）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MacBook 用户专用的 ESP32 主机侧工具集，发布为 `@esptool/mac`。当前提供基于 `@stoprocent/noble` 的 BLE 扫描（经本机蓝牙适配器发现周边 BLE 广播设备）。
+
+## 使用（消费约定与 @esptool/cli 相同）
+
+```bash
+npx -y @esptool/mac scan      # 扫描 10s（⏳ 待发布，发布前用下面的本地方式）
+```
+
+本地开发：
+
+```bash
+bun install
+bun bin/cli.js scan -t 8     # 指定时长；-t 0 持续扫描直到 Ctrl+C
+bun bin/cli.js scan -n S3    # 按设备名过滤
+bun bin/cli.js scan -u ffff  # 按广播 service UUID 过滤（BluFi 设备指纹）
+bun bin/cli.js scan -o       # 只显示本仓库设备（规则见 OUR_SIGNATURES）
+bun bin/cli.js scan -j       # JSON 输出（不含表头与实时行，可直接管道给 jq/node）
+```
+
+## 说明
+
+- 运行时兼容 node 与 bun：bin 入口 `#!/usr/bin/env node`（npx 场景），本地也可 `bun bin/cli.js` 直跑。
+- macOS 下设备 id 是 CoreBluetooth 生成的随机 UUID，非真实 MAC。
+- 依赖安装时 bun 会阻止 `bluetooth-hci-socket` 的 postinstall（Linux 原生模块），macOS 无需信任，不影响使用。
+- 发布：`bun run release`（npm version patch + bun publish）。
+
+## 文档
+
+- [BLE 扫描 PoC 工作报告](docs/2026-10-25-scan-poc-report.md)
+- [BLE 广播标识统一规范提案](docs/2026-10-25-ble-advertising-spec-proposal.md)

package/bin/cli.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+import noble from '@stoprocent/noble'
+
+const HELP = `
+@esptool/mac — MacBook 专用主机工具（BLE 扫描等）
+
+用法: npx @esptool/mac scan [选项]
+  或: bun bin/cli.js scan [选项]
+
+选项:
+  -t, --timeout <秒>     扫描时长 (默认 10, 0 = 持续扫描直到 Ctrl+C)
+  -n, --name <关键字>    按设备名过滤 (大小写不敏感)
+  -u, --service <uuid>   按广播 service UUID 过滤 (如 ffff, 忽略大小写与连字符)
+  -o, --our              只显示本仓库设备 (BluFi ffff 服务, 或 KDB- 名字前缀)
+  -d, --duplicates       响应重复广播 (实时刷新 RSSI)
+  -j, --json             以 JSON 输出最终结果
+  -h, --help             显示帮助
+`
+
+const normalizeUuid = (uuid) => String(uuid).replace(/-/g, '').toLowerCase()
+
+// 自家设备识别：命中任一签名即算。多条并存是为了覆盖规范落地前后各种形态，
+// 随命名规范推进逐步收紧（见 docs/2026-10-25-ble-advertising-spec-proposal.md §2/§3）。
+const OUR_SIGNATURES = [
+  { service: 'ffff' }, // BluFi 配网固件
+  { namePrefix: 'kdb-' }, // 完整格式名 KDB-<产品线>-<型号>-<标识>
+  { namePattern: /^[a-z]{2}-[0-9a-f]{2}$/ }, // 短码 <产品线2>-<MAC末1字节hex2>，如 S3-1F
+]
+
+const isOurs = (name, services) => {
+  const lowerName = name.toLowerCase()
+  return OUR_SIGNATURES.some(
+    (sig) =>
+      (sig.service && services.some((s) => s === sig.service || s.endsWith(sig.service))) ||
+      (sig.namePrefix && lowerName.startsWith(sig.namePrefix)) ||
+      (sig.namePattern && sig.namePattern.test(lowerName))
+  )
+}
+
+const parseArgs = (argv) => {
+  const opts = { timeout: 10, name: '', service: '', our: false, duplicates: false, json: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '-t' || a === '--timeout') opts.timeout = Number(argv[++i])
+    else if (a === '-n' || a === '--name') opts.name = argv[++i]
+    else if (a === '-u' || a === '--service') opts.service = normalizeUuid(argv[++i])
+    else if (a === '-o' || a === '--our') opts.our = true
+    else if (a === '-d' || a === '--duplicates') opts.duplicates = true
+    else if (a === '-j' || a === '--json') opts.json = true
+    else if (a === '-h' || a === '--help') {
+      console.log(HELP)
+      process.exit(0)
+    } else {
+      console.error(`未知参数: ${a}`)
+      console.log(HELP)
+      process.exit(1)
+    }
+  }
+  return opts
+}
+
+const toHex = (buf) => (Buffer.isBuffer(buf) ? buf.toString('hex') : '')
+
+const toRecords = (devices) =>
+  [...devices.values()].sort((x, y) => y.rssi - x.rssi)
+
+const printTable = (records, elapsed) => {
+  console.log(`\n共发现 ${records.length} 台设备 (耗时 ${elapsed}s)，按信号强度排序:\n`)
+  const pad = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s.padEnd(n))
+  console.log(`  ${'RSSI'.padStart(8)}  ${pad('UUID / ADDRESS', 38)}${pad('NAME', 24)}${pad('SERVICES', 10)}MFG DATA`)
+  for (const d of records) {
+    const services = d.services.join(',')
+    console.log(
+      `  ${`${d.rssi} dBm`.padStart(8)}  ${pad(d.id, 38)}${pad(d.name || '(未命名)', 24)}${pad(services, 10)}${d.mfg}`
+    )
+  }
+}
+
+const scan = async (opts) => {
+  const devices = new Map()
+  const startedAt = Date.now()
+
+  noble.on('discover', (p) => {
+    const name = p.advertisement?.localName || ''
+    if (opts.name && !name.toLowerCase().includes(opts.name.toLowerCase())) return
+
+    const services = (p.advertisement?.serviceUuids ?? []).map(normalizeUuid)
+    if (opts.service && !services.some((s) => s === opts.service || s.endsWith(opts.service))) return
+    if (opts.our && !isOurs(name, services)) return
+
+    const prev = devices.get(p.id)
+    if (prev) {
+      prev.rssi = p.rssi
+      prev.count += 1
+      if (!prev.name && name) prev.name = name
+      if (!prev.services.length && services.length) prev.services = services
+      if (!opts.duplicates) return
+    } else {
+      devices.set(p.id, {
+        id: p.id,
+        name,
+        rssi: p.rssi,
+        connectable: p.connectable ?? null,
+        mfg: toHex(p.advertisement?.manufacturerData),
+        services,
+        firstSeen: Date.now() - startedAt,
+        count: 1,
+      })
+      if (!opts.json) {
+        const elapsed = ((Date.now() - startedAt) / 1000).toFixed(1)
+        console.log(`  [${elapsed.padStart(5)}s] ${String(p.rssi).padStart(4)} dBm  ${p.id}  ${name || '(未命名)'}`)
+      }
+    }
+  })
+
+  await new Promise((resolve, reject) => {
+    const onState = (state) => (state === 'poweredOn' ? resolve() : undefined)
+    noble.on('stateChange', onState)
+    noble.on('warning', (w) => console.error(`[noble] ${w}`))
+    if (noble.state === 'poweredOn') resolve()
+    setTimeout(() => reject(new Error(`蓝牙适配器未就绪 (state: ${noble.state})`)), 5000)
+  })
+
+  if (!opts.json) {
+    console.log(`开始扫描 (${opts.timeout === 0 ? '持续模式, Ctrl+C 结束' : `${opts.timeout}s`})…\n`)
+  }
+  await noble.startScanningAsync([], opts.duplicates)
+
+  const finish = async () => {
+    noble.removeAllListeners('discover')
+    await noble.stopScanningAsync().catch(() => {})
+    const elapsed = ((Date.now() - startedAt) / 1000).toFixed(1)
+    const records = toRecords(devices)
+    if (opts.json) {
+      console.log(JSON.stringify({ elapsed: Number(elapsed), count: records.length, devices: records }, null, 2))
+    } else {
+      printTable(records, elapsed)
+    }
+    process.exit(0)
+  }
+
+  process.on('SIGINT', finish)
+  if (opts.timeout > 0) setTimeout(finish, opts.timeout * 1000)
+}
+
+const main = async () => {
+  const [cmd, ...rest] = process.argv.slice(2)
+  if (cmd !== 'scan') {
+    console.log(HELP)
+    process.exit(cmd ? 1 : 0)
+  }
+  await scan(parseArgs(rest))
+}
+
+main().catch((err) => {
+  console.error(`错误: ${err.message}`)
+  process.exit(1)
+})

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@esptool/mac",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.4",
+  "description": "MacBook host-side tools for ESP32 workflow - BLE scanner and more",
+  "type": "module",
+  "bin": {
+    "mac": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "scan": "bun bin/cli.js scan",
+    "test": "node bin/cli.js scan -t 3",
+    "release": "npm version patch && npm publish --access public"
+  },
+  "dependencies": {
+    "@stoprocent/noble": "^2.3.2"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "esp32",
+    "bluetooth",
+    "ble",
+    "scanner",
+    "macos",
+    "macbook",
+    "blufi",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "Benz <ben.zeng@keepdb.com>"
+}