kg-ios-usb-app-info 0.1.0

package/bin/kg-ios-usb-app-info.mjs

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+
+import {
+  findDebugServers,
+  getUiTree,
+  debugScan
+} from '../lib/kg-ios-usb-debug.mjs';
+
+const VERSION = '0.1.0';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function getArgValue(name) {
+  const index = args.indexOf(name);
+  if (index < 0) return undefined;
+
+  const value = args[index + 1];
+  if (!value || value.startsWith('--')) {
+    return undefined;
+  }
+
+  return value;
+}
+
+function hasArg(name) {
+  return args.includes(name);
+}
+
+function parseInteger(value, fallback) {
+  if (!value) return fallback;
+
+  const number = Number(value);
+  if (!Number.isInteger(number)) {
+    return fallback;
+  }
+
+  return number;
+}
+
+function parsePorts(value) {
+  if (!value) return undefined;
+
+  const ports = [];
+
+  for (const part of value.split(',')) {
+    const item = part.trim();
+    if (!item) continue;
+
+    if (item.includes('-')) {
+      const [startText, endText] = item.split('-');
+      const start = Number(startText);
+      const end = Number(endText);
+
+      if (
+        Number.isInteger(start) &&
+        Number.isInteger(end) &&
+        start > 0 &&
+        end >= start
+      ) {
+        for (let port = start; port <= end; port++) {
+          ports.push(port);
+        }
+      }
+
+      continue;
+    }
+
+    const port = Number(item);
+    if (Number.isInteger(port) && port > 0) {
+      ports.push(port);
+    }
+  }
+
+  return ports.length ? [...new Set(ports)] : undefined;
+}
+
+function printJson(value, pretty = true) {
+  console.log(JSON.stringify(value, null, pretty ? 2 : 0));
+}
+
+function printHelp() {
+  console.log(`
+kg-ios-usb-app-info
+
+Usage:
+  kg-ios-usb-app-info list
+  kg-ios-usb-app-info tree
+  kg-ios-usb-app-info tree --bundle-id com.xxx.app
+  kg-ios-usb-app-info tree --raw
+  kg-ios-usb-app-info scan
+  kg-ios-usb-app-info help
+
+Commands:
+  list        List iOS Debug UI Servers over USB
+  tree        Read current iOS app UI hierarchy over USB
+  scan        Diagnose USB devices and debug ports
+  help        Show help
+  version     Show version
+
+Options:
+  --bundle-id <id>        Specify app bundleId when multiple apps are found
+  --ports <ports>         Specify ports, e.g. 18080 or 18080,18081 or 18080-18100
+  --server-name <name>    Specify debug server name, default KGDebugUIServer
+  --concurrency <n>       Specify scan concurrency, default from lib
+  --compact               Output compact JSON
+  --raw                   For tree command, output only raw UI tree JSON
+
+Environment:
+  KG_IOS_USB_PORTS                 Default ports, e.g. 18080,18081 or 18080-18100
+  KG_IOS_USB_SERVER_NAME           Default server name
+  KG_IOS_USB_DEBUG_TOKEN           Debug token sent as X-Debug-Token
+  KG_IOS_USB_CONNECT_TIMEOUT_MS    USB connect timeout
+  KG_IOS_USB_READ_TIMEOUT_MS       HTTP read timeout
+  KG_IOS_USB_TREE_TIMEOUT_MS       UI tree read timeout
+
+Examples:
+  kg-ios-usb-app-info list
+  kg-ios-usb-app-info tree
+  kg-ios-usb-app-info tree --bundle-id com.kugou.tingshu
+  kg-ios-usb-app-info tree --ports 18080 --raw
+  kg-ios-usb-app-info scan --ports 18080-18100
+`);
+}
+
+function printVersion() {
+  console.log(`kg-ios-usb-app-info ${VERSION}`);
+}
+
+function buildOptions() {
+  const bundleId = getArgValue('--bundle-id');
+  const ports = parsePorts(getArgValue('--ports'));
+  const serverName = getArgValue('--server-name');
+  const concurrency = parseInteger(getArgValue('--concurrency'), undefined);
+
+  const options = {};
+
+  if (bundleId) {
+    options.bundleId = bundleId;
+  }
+
+  if (ports) {
+    options.ports = ports;
+  }
+
+  if (serverName) {
+    options.serverName = serverName;
+  }
+
+  if (concurrency) {
+    options.concurrency = concurrency;
+  }
+
+  return options;
+}
+
+async function handleList(cliOptions) {
+  const servers = await findDebugServers(cliOptions.queryOptions);
+
+  printJson({
+    ok: true,
+    count: servers.length,
+    servers
+  }, cliOptions.pretty);
+}
+
+async function handleTree(cliOptions) {
+  const result = await getUiTree(cliOptions.queryOptions);
+
+  if (cliOptions.raw) {
+    printJson(result.tree, cliOptions.pretty);
+    return;
+  }
+
+  printJson({
+    ok: true,
+    target: result.target,
+    tree: result.tree
+  }, cliOptions.pretty);
+}
+
+async function handleScan(cliOptions) {
+  const result = await debugScan(cliOptions.queryOptions);
+
+  printJson({
+    ok: true,
+    ...result
+  }, cliOptions.pretty);
+}
+
+async function main() {
+  const pretty = !hasArg('--compact');
+  const raw = hasArg('--raw');
+
+  const cliOptions = {
+    pretty,
+    raw,
+    queryOptions: buildOptions()
+  };
+
+  if (
+    !command ||
+    command === 'help' ||
+    command === '--help' ||
+    command === '-h'
+  ) {
+    printHelp();
+    return;
+  }
+
+  if (
+    command === 'version' ||
+    command === '--version' ||
+    command === '-v'
+  ) {
+    printVersion();
+    return;
+  }
+
+  if (command === 'list') {
+    await handleList(cliOptions);
+    return;
+  }
+
+  if (command === 'tree') {
+    await handleTree(cliOptions);
+    return;
+  }
+
+  if (command === 'scan') {
+    await handleScan(cliOptions);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+function flushStdout() {
+  return new Promise(resolve => {
+    process.stdout.write('', resolve);
+  });
+}
+
+main()
+  .then(async () => {
+    await flushStdout();
+    process.exit(0);
+  })
+  .catch(async error => {
+    printJson({
+      ok: false,
+      error: error?.message || String(error)
+    }, true);
+
+    await flushStdout();
+    process.exit(1);
+  });
+
+
+

package/lib/kg-ios-usb-debug.mjs

@@ -0,0 +1,565 @@
+import { UsbmuxClient } from 'usbmux-client';
+
+const DEFAULT_SERVER_NAME = process.env.KG_IOS_USB_SERVER_NAME || 'KGDebugUIServer';
+
+// 默认扫描 18080~18100
+// 也可以通过环境变量指定：
+// KG_IOS_USB_PORTS=18080
+// KG_IOS_USB_PORTS=18080,18081,18090-18100
+const DEFAULT_PORTS = parsePorts(process.env.KG_IOS_USB_PORTS) ||
+  Array.from({ length: 21 }, (_, i) => 18080 + i);
+
+const DEFAULT_CONNECT_TIMEOUT_MS = Number(process.env.KG_IOS_USB_CONNECT_TIMEOUT_MS || 1200);
+const DEFAULT_READ_TIMEOUT_MS = Number(process.env.KG_IOS_USB_READ_TIMEOUT_MS || 2000);
+const TREE_READ_TIMEOUT_MS = Number(process.env.KG_IOS_USB_TREE_TIMEOUT_MS || 15000);
+const MAX_RESPONSE_BYTES = Number(process.env.KG_IOS_USB_MAX_RESPONSE_BYTES || 50 * 1024 * 1024);
+
+function parsePorts(value) {
+  if (!value) return null;
+
+  const ports = [];
+
+  for (const part of value.split(',')) {
+    const item = part.trim();
+    if (!item) continue;
+
+    if (item.includes('-')) {
+      const [startText, endText] = item.split('-');
+      const start = Number(startText);
+      const end = Number(endText);
+
+      if (
+        Number.isInteger(start) &&
+        Number.isInteger(end) &&
+        start > 0 &&
+        end >= start
+      ) {
+        for (let port = start; port <= end; port++) {
+          ports.push(port);
+        }
+      }
+
+      continue;
+    }
+
+    const port = Number(item);
+    if (Number.isInteger(port) && port > 0) {
+      ports.push(port);
+    }
+  }
+
+  return ports.length ? [...new Set(ports)] : null;
+}
+
+function normalizeDevices(devices) {
+  if (Array.isArray(devices)) {
+    return devices.map((raw, index) => {
+      const id = raw.DeviceID ?? raw.deviceId ?? raw.id ?? index;
+      return {
+        id,
+        raw
+      };
+    });
+  }
+
+  return Object.entries(devices || {}).map(([id, raw]) => ({
+    id,
+    raw
+  }));
+}
+
+function createTimeoutError(label, timeoutMs) {
+  return new Error(`${label} timeout after ${timeoutMs}ms`);
+}
+
+function withTimeout(promise, timeoutMs, label) {
+  let timer;
+
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(createTimeoutError(label, timeoutMs));
+    }, timeoutMs);
+
+    if (typeof timer.unref === 'function') {
+      timer.unref();
+    }
+  });
+
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    clearTimeout(timer);
+  });
+}
+
+function safeDestroySocket(socket) {
+  if (!socket) return;
+
+  try {
+    socket.destroy();
+  } catch {
+    // ignore
+  }
+}
+
+function parseHeaderLines(headerText) {
+  const lines = headerText.split('\r\n');
+  const statusLine = lines.shift() || '';
+
+  const headers = {};
+  for (const line of lines) {
+    const index = line.indexOf(':');
+    if (index < 0) continue;
+
+    const key = line.slice(0, index).trim().toLowerCase();
+    const value = line.slice(index + 1).trim();
+
+    if (!key) continue;
+    headers[key] = value;
+  }
+
+  const statusMatch = statusLine.match(/^HTTP\/\d(?:\.\d)?\s+(\d+)/i);
+  const statusCode = statusMatch ? Number(statusMatch[1]) : 0;
+
+  return {
+    statusLine,
+    statusCode,
+    headers
+  };
+}
+
+function decodeChunkedBody(buffer) {
+  let offset = 0;
+  const chunks = [];
+
+  while (offset < buffer.length) {
+    const lineEnd = buffer.indexOf(Buffer.from('\r\n'), offset);
+    if (lineEnd < 0) break;
+
+    const sizeLine = buffer.subarray(offset, lineEnd).toString('utf8').trim();
+    const semicolonIndex = sizeLine.indexOf(';');
+    const sizeText = semicolonIndex >= 0 ? sizeLine.slice(0, semicolonIndex) : sizeLine;
+    const size = Number.parseInt(sizeText, 16);
+
+    if (!Number.isFinite(size)) break;
+
+    offset = lineEnd + 2;
+
+    if (size === 0) {
+      break;
+    }
+
+    const chunkEnd = offset + size;
+    if (chunkEnd > buffer.length) break;
+
+    chunks.push(buffer.subarray(offset, chunkEnd));
+    offset = chunkEnd + 2;
+  }
+
+  return Buffer.concat(chunks);
+}
+
+function parseHttpResponse(buffer) {
+  const headerEnd = buffer.indexOf(Buffer.from('\r\n\r\n'));
+
+  if (headerEnd < 0) {
+    return {
+      statusCode: 0,
+      statusLine: '',
+      headers: {},
+      rawHeaders: '',
+      bodyBuffer: buffer,
+      body: buffer.toString('utf8')
+    };
+  }
+
+  const rawHeaders = buffer.subarray(0, headerEnd).toString('utf8');
+  const parsed = parseHeaderLines(rawHeaders);
+
+  let bodyBuffer = buffer.subarray(headerEnd + 4);
+
+  const transferEncoding = parsed.headers['transfer-encoding'] || '';
+  if (transferEncoding.toLowerCase().includes('chunked')) {
+    bodyBuffer = decodeChunkedBody(bodyBuffer);
+  }
+
+  return {
+    statusCode: parsed.statusCode,
+    statusLine: parsed.statusLine,
+    headers: parsed.headers,
+    rawHeaders,
+    bodyBuffer,
+    body: bodyBuffer.toString('utf8')
+  };
+}
+
+function hasCompleteHttpResponse(buffer) {
+  const headerEnd = buffer.indexOf(Buffer.from('\r\n\r\n'));
+  if (headerEnd < 0) return false;
+
+  const headerText = buffer.subarray(0, headerEnd).toString('utf8');
+  const { headers } = parseHeaderLines(headerText);
+
+  const contentLengthText = headers['content-length'];
+  if (contentLengthText) {
+    const contentLength = Number(contentLengthText);
+    if (Number.isFinite(contentLength)) {
+      const totalLength = headerEnd + 4 + contentLength;
+      return buffer.length >= totalLength;
+    }
+  }
+
+  const transferEncoding = headers['transfer-encoding'] || '';
+  if (transferEncoding.toLowerCase().includes('chunked')) {
+    return buffer.includes(Buffer.from('\r\n0\r\n\r\n'), headerEnd + 4);
+  }
+
+  return false;
+}
+
+function readHttpResponse(socket, timeoutMs = DEFAULT_READ_TIMEOUT_MS) {
+  return new Promise((resolve, reject) => {
+    let buffer = Buffer.alloc(0);
+    let finished = false;
+    let timer = null;
+
+    function resetTimer() {
+      clearTimeout(timer);
+
+      timer = setTimeout(() => {
+        if (buffer.length > 0) {
+          finish(null, buffer);
+        } else {
+          finish(createTimeoutError('HTTP read', timeoutMs));
+        }
+      }, timeoutMs);
+
+      if (typeof timer.unref === 'function') {
+        timer.unref();
+      }
+    }
+
+    function cleanup() {
+      clearTimeout(timer);
+      socket.off('data', onData);
+      socket.off('end', onEnd);
+      socket.off('close', onClose);
+      socket.off('error', onError);
+    }
+
+    function finish(error, data) {
+      if (finished) return;
+      finished = true;
+
+      cleanup();
+
+      if (error) {
+        reject(error);
+      } else {
+        resolve(data || buffer);
+      }
+    }
+
+    function onData(chunk) {
+      buffer = Buffer.concat([buffer, chunk]);
+
+      if (buffer.length > MAX_RESPONSE_BYTES) {
+        finish(new Error(`HTTP response too large: ${buffer.length} bytes`));
+        return;
+      }
+
+      if (hasCompleteHttpResponse(buffer)) {
+        finish(null, buffer);
+        return;
+      }
+
+      resetTimer();
+    }
+
+    function onEnd() {
+      finish(null, buffer);
+    }
+
+    function onClose() {
+      if (buffer.length > 0) {
+        finish(null, buffer);
+      } else {
+        finish(new Error('socket closed without response'));
+      }
+    }
+
+    function onError(error) {
+      finish(error);
+    }
+
+    socket.on('data', onData);
+    socket.on('end', onEnd);
+    socket.on('close', onClose);
+    socket.on('error', onError);
+
+    resetTimer();
+  });
+}
+
+async function requestDeviceHttp(client, deviceId, port, path, options = {}) {
+  const {
+    connectTimeoutMs = DEFAULT_CONNECT_TIMEOUT_MS,
+    readTimeoutMs = DEFAULT_READ_TIMEOUT_MS,
+    method = 'GET'
+  } = options;
+
+  let socket;
+
+  try {
+    socket = await withTimeout(
+      client.createDeviceTunnel(deviceId, port),
+      connectTimeoutMs,
+      `connect device=${deviceId} port=${port}`
+    );
+
+    const headers = [
+      `${method} ${path} HTTP/1.1`,
+      'Host: 127.0.0.1',
+      'Accept: application/json',
+      'User-Agent: kg-ios-usb-app-info/0.1.0',
+      'Connection: close'
+    ];
+
+    const token = process.env.KG_IOS_USB_DEBUG_TOKEN;
+    if (token) {
+      headers.push(`X-Debug-Token: ${token}`);
+    }
+
+    headers.push('', '');
+
+    socket.write(headers.join('\r\n'));
+
+    const responseBuffer = await readHttpResponse(socket, readTimeoutMs);
+    return parseHttpResponse(responseBuffer);
+  } finally {
+    safeDestroySocket(socket);
+  }
+}
+
+async function requestDeviceJson(client, deviceId, port, path, options = {}) {
+  const response = await requestDeviceHttp(client, deviceId, port, path, options);
+
+  if (response.statusCode && (response.statusCode < 200 || response.statusCode >= 300)) {
+    throw new Error(
+      `HTTP ${response.statusCode} from device=${deviceId} port=${port} path=${path}: ` +
+      response.body.slice(0, 300)
+    );
+  }
+
+  try {
+    return JSON.parse(response.body);
+  } catch (error) {
+    throw new Error(
+      `Invalid JSON from device=${deviceId} port=${port} path=${path}: ` +
+      `${error.message}; body=${response.body.slice(0, 300)}`
+    );
+  }
+}
+
+async function getDevices() {
+  const client = new UsbmuxClient();
+
+  const rawDevices = await withTimeout(
+    client.getDevices(),
+    3000,
+    'get USB devices'
+  );
+
+  return {
+    client,
+    devices: normalizeDevices(rawDevices),
+    rawDevices
+  };
+}
+
+async function mapWithConcurrency(items, concurrency, mapper) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+
+  async function worker() {
+    while (nextIndex < items.length) {
+      const currentIndex = nextIndex;
+      nextIndex += 1;
+
+      results[currentIndex] = await mapper(items[currentIndex], currentIndex);
+    }
+  }
+
+  const workerCount = Math.min(concurrency, items.length);
+  await Promise.all(Array.from({ length: workerCount }, worker));
+
+  return results;
+}
+
+function buildCandidates(devices, ports) {
+  const candidates = [];
+
+  for (const device of devices) {
+    for (const port of ports) {
+      candidates.push({
+        device,
+        port
+      });
+    }
+  }
+
+  return candidates;
+}
+
+export async function findDebugServers(options = {}) {
+  const {
+    bundleId,
+    ports = DEFAULT_PORTS,
+    serverName = DEFAULT_SERVER_NAME,
+    concurrency = 6
+  } = options;
+
+  const { client, devices } = await getDevices();
+  const candidates = buildCandidates(devices, ports);
+
+  const results = await mapWithConcurrency(
+    candidates,
+    concurrency,
+    async ({ device, port }) => {
+      try {
+        const json = await requestDeviceJson(
+          client,
+          device.id,
+          port,
+          '/debug/ping',
+          {
+            connectTimeoutMs: DEFAULT_CONNECT_TIMEOUT_MS,
+            readTimeoutMs: DEFAULT_READ_TIMEOUT_MS
+          }
+        );
+
+        if (json?.server !== serverName) {
+          return null;
+        }
+
+        if (bundleId && json.bundleId !== bundleId) {
+          return null;
+        }
+
+        return {
+          deviceId: device.id,
+          port,
+          bundleId: json.bundleId || '',
+          appName: json.appName || '',
+          server: json.server || '',
+          ping: json,
+          device: device.raw
+        };
+      } catch {
+        return null;
+      }
+    }
+  );
+
+  return results.filter(Boolean);
+}
+
+async function getSingleDebugServer(options = {}) {
+  const { bundleId } = options;
+  const servers = await findDebugServers(options);
+
+  if (servers.length === 0) {
+    throw new Error(
+      bundleId
+        ? `没有找到 bundleId=${bundleId} 的 iOS Debug UI Server`
+        : '没有找到 iOS Debug UI Server。请确认 USB 已连接、iPhone 已信任电脑、App 在前台、GCDWebServer 已启动，并且 /debug/ping 可访问。'
+    );
+  }
+
+  if (servers.length > 1 && !bundleId) {
+    throw new Error(
+      '找到多个 Debug UI Server，请使用 --bundle-id 指定：\n' +
+      servers
+        .map(server => {
+          return `${server.bundleId} app=${server.appName} device=${server.deviceId} port=${server.port}`;
+        })
+        .join('\n')
+    );
+  }
+
+  return servers[0];
+}
+
+export async function getUiTree(options = {}) {
+  const target = await getSingleDebugServer(options);
+  const client = new UsbmuxClient();
+
+  const tree = await requestDeviceJson(
+    client,
+    target.deviceId,
+    target.port,
+    '/debug/ui/tree',
+    {
+      connectTimeoutMs: DEFAULT_CONNECT_TIMEOUT_MS,
+      readTimeoutMs: TREE_READ_TIMEOUT_MS
+    }
+  );
+
+  return {
+    target,
+    tree
+  };
+}
+
+export async function debugScan(options = {}) {
+  const {
+    ports = DEFAULT_PORTS,
+    concurrency = 6
+  } = options;
+
+  const { client, devices, rawDevices } = await getDevices();
+  const candidates = buildCandidates(devices, ports);
+
+  const results = await mapWithConcurrency(
+    candidates,
+    concurrency,
+    async ({ device, port }) => {
+      try {
+        const response = await requestDeviceHttp(
+          client,
+          device.id,
+          port,
+          '/debug/ping',
+          {
+            connectTimeoutMs: DEFAULT_CONNECT_TIMEOUT_MS,
+            readTimeoutMs: DEFAULT_READ_TIMEOUT_MS
+          }
+        );
+
+        return {
+          deviceId: device.id,
+          port,
+          ok: true,
+          statusCode: response.statusCode,
+          headers: response.headers,
+          body: response.body
+        };
+      } catch (error) {
+        return {
+          deviceId: device.id,
+          port,
+          ok: false,
+          error: error?.message || String(error)
+        };
+      }
+    }
+  );
+
+  return {
+    rawDevices,
+    devices,
+    ports,
+    results
+  };
+}
+
+
+

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "kg-ios-usb-app-info",
+  "version": "0.1.0",
+  "description": "Read iOS app UI hierarchy and app info through USB for AI tools",
+  "type": "module",
+  "bin": {
+    "kg-ios-usb-app-info": "bin/kg-ios-usb-app-info.mjs"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "dependencies": {
+    "usbmux-client": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}
+
+