@nickname4th/pura-cli 0.1.0 → 0.1.2

package/README.md

@@ -20,7 +20,7 @@ Open the Hub:
 http://<hub-lan-ip>:8787
 ```
 
-On each developer machine, connect an Agent:
+On each developer machine, connect an Agent. After this command starts, the Hub page shows every authorized Android device attached to this machine:
 
 ```bash
 npx @nickname4th/pura-cli connect <hub-lan-ip>:8787 --name "Zhang San"
@@ -33,13 +33,7 @@ npm install -g @nickname4th/pura-cli
 pura-cli connect <hub-lan-ip>:8787 --name "Zhang San" --background
 ```
 
-Publish the local Android device:
-
-```bash
-npx @nickname4th/pura-cli connect device --name "Zhang San Pixel 8" --owner "Zhang San" --note "login branch"
-```
-
-Designers can now pick the published machine on the Hub homepage, open the live screen, and click on it with a mouse.
+Open the Hub page, find the device under devices to publish, and publish it from the web UI. Designers can then pick the published machine on the Hub homepage, open the live screen, and click on it with a mouse.
 
 ## Project Site
 
@@ -105,13 +99,13 @@ pura-cli hub --host 0.0.0.0 --port 8787
 
 ## Developer Agent
 
-Each developer connects their local Agent to the Hub:
+Each developer connects their local Agent to the Hub. Once connected, the Hub web UI lists all authorized local Android devices, including devices that are not published yet:
 
 ```bash
 pura-cli connect 192.168.100.128:8787 --name "Zhang San"
 ```
 
-The Agent listens on `8788` by default and continuously reports local ADB devices to the Hub.
+The Agent listens on `8788` by default and continuously reports local ADB devices to the Hub. Use the web UI to publish, rename, unpublish, and manage devices.
 
 If the Hub cannot reach the auto-detected Agent URL, specify it:
 
@@ -140,7 +134,15 @@ Connect a phone over USB and confirm it is authorized:
 adb devices -l
 ```
 
-Then publish it:
+Then run or install the Agent:
+
+```bash
+pura-cli connect 192.168.100.128:8787 --name "Zhang San" --background
+```
+
+Open the Hub page and publish the device from the web UI.
+
+The CLI also has a shortcut for scripts:
 
 ```bash
 pura-cli connect device --name "Zhang San Pixel 8" --owner "Zhang San" --note "login branch"
@@ -211,7 +213,7 @@ Release flow:
 1. Update `version` in `package.json`.
 2. Run `npm run check`, `npm run build`, and `npm pack --dry-run`.
 3. Push a tag like `v0.1.0`.
-4. GitHub Actions publishes `pura-cli` to npm and `ghcr.io/liutianjie/pura` to GHCR.
+4. GitHub Actions publishes `@nickname4th/pura-cli` to npm and `ghcr.io/liutianjie/pura` to GHCR.
 
 The release workflow requires an `NPM_TOKEN` repository secret.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nickname4th/pura-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "LAN Android device mirroring hub and developer CLI for distributed teams.",
   "license": "MIT",
   "type": "module",

package/server/dist/adb.js

@@ -1,7 +1,10 @@
 import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
-const ADB = process.env.ADB_PATH ?? "adb";
+const ADB = resolveAdbCommand();
 const INCLUDE_TCP_DEVICES = process.env.INCLUDE_TCP_DEVICES === "true";
 export function adbCommand(args) {
     return {
@@ -151,6 +154,18 @@ export async function getDisplaySize(serial) {
 function clamp(value, min, max) {
     return Math.max(min, Math.min(max, value));
 }
+function resolveAdbCommand() {
+    if (process.env.ADB_PATH)
+        return process.env.ADB_PATH;
+    const sdkRoot = process.env.ANDROID_HOME ?? process.env.ANDROID_SDK_ROOT;
+    const candidates = [
+        sdkRoot ? path.join(sdkRoot, "platform-tools", "adb") : "",
+        path.join(os.homedir(), "Library", "Android", "sdk", "platform-tools", "adb"),
+        "/opt/homebrew/bin/adb",
+        "/usr/local/bin/adb"
+    ].filter(Boolean);
+    return candidates.find((candidate) => fs.existsSync(candidate)) ?? "adb";
+}
 const keyEvents = {
     back: "KEYCODE_BACK",
     home: "KEYCODE_HOME",

package/server/dist/cli.js

@@ -59,7 +59,7 @@ async function handleConnect() {
     console.log(`pura-cli saved hub: ${hubUrl}`);
     console.log(`agent URL announced to hub: ${publicUrl}`);
     if (hasFlag("--background") || hasFlag("--install")) {
-        installLaunchAgent();
+        await installLaunchAgent();
         return;
     }
     console.log(`pura-cli starting agent: ${agentName} (${agentId})`);
@@ -77,7 +77,7 @@ async function handleConnect() {
 }
 async function handleAutoConnect() {
     if (hasFlag("--install")) {
-        installLaunchAgent();
+        await installLaunchAgent();
         return;
     }
     if (hasFlag("--uninstall")) {
@@ -119,6 +119,7 @@ async function publishLocalDevice() {
         process.exit(1);
     }
     console.log(`Published ${label} (${serial}) to ${config.hubUrl ?? "configured hub"}`);
+    await printPublicationVisibility(config, agentPort, serial);
 }
 function startSavedAgent(config) {
     const port = readFlag("--port") ?? config.agentPort ?? "8788";
@@ -150,7 +151,7 @@ function startSavedAgent(config) {
         DATA_DIR: dataDir
     });
 }
-function installLaunchAgent() {
+async function installLaunchAgent() {
     const config = readConfig();
     if (!config.hubUrl) {
         console.error("No saved hub found. Run `pura-cli connect <hub-url> --name <name>` once first.");
@@ -174,6 +175,7 @@ function installLaunchAgent() {
     if (cliPath.includes(`${path.sep}_npx${path.sep}`)) {
         console.warn("This was installed from an npx cache path. For long-term use, install pura-cli globally and run the install command again.");
     }
+    await printAgentVisibility(config);
 }
 function uninstallLaunchAgent() {
     if (process.platform !== "darwin") {
@@ -202,6 +204,16 @@ function printLaunchAgentStatus() {
     }
 }
 function makeLaunchAgentPlist(nodePath, cliPath) {
+    const environment = {
+        PATH: process.env.PATH,
+        ANDROID_HOME: process.env.ANDROID_HOME,
+        ANDROID_SDK_ROOT: process.env.ANDROID_SDK_ROOT,
+        ADB_PATH: findExecutable("adb")
+    };
+    const environmentEntries = Object.entries(environment)
+        .filter((entry) => Boolean(entry[1]))
+        .map(([key, value]) => `    <key>${escapeXml(key)}</key>\n    <string>${escapeXml(value)}</string>`)
+        .join("\n");
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -218,6 +230,10 @@ function makeLaunchAgentPlist(nodePath, cliPath) {
   <true/>
   <key>KeepAlive</key>
   <true/>
+  <key>EnvironmentVariables</key>
+  <dict>
+${environmentEntries}
+  </dict>
   <key>StandardOutPath</key>
   <string>${escapeXml(path.join(os.homedir(), "Library", "Logs", "pura-agent.log"))}</string>
   <key>StandardErrorPath</key>
@@ -254,6 +270,16 @@ function resolveAgentDataDir(value) {
         return path.join(os.homedir(), ".pura", "agent-data");
     return path.isAbsolute(value) ? value : path.resolve(value);
 }
+function findExecutable(name) {
+    for (const directory of (process.env.PATH ?? "").split(path.delimiter)) {
+        if (!directory)
+            continue;
+        const candidate = path.join(directory, name);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
 function startServer(env) {
     const child = spawn(process.execPath, [new URL("./index.js", import.meta.url).pathname], {
         stdio: "inherit",
@@ -264,6 +290,97 @@ function startServer(env) {
     });
     child.on("exit", (code) => process.exit(code ?? 0));
 }
+async function printAgentVisibility(config) {
+    const agentId = config.agentId;
+    const hubUrl = config.hubUrl;
+    const port = config.agentPort ?? "8788";
+    if (!agentId || !hubUrl)
+        return;
+    const result = await waitForAgentVisibility({ agentId, hubUrl, port });
+    if (result.visible) {
+        console.log(`Agent is online. Local devices: ${result.localDevices?.length ?? 0}. Devices visible on Hub: ${result.hubDevices?.length ?? 0}.`);
+        console.log(`Open ${hubUrl} to publish or control devices.`);
+        return;
+    }
+    console.warn("Agent was installed, but the Hub did not report the local device list yet.");
+    if (result.localError)
+        console.warn(`Local Agent check: ${result.localError}`);
+    if (result.hubError)
+        console.warn(`Hub check: ${result.hubError}`);
+    console.warn(`Check logs: tail -f ${path.join(os.homedir(), "Library", "Logs", "pura-agent.err.log")}`);
+}
+async function printPublicationVisibility(config, agentPort, serial) {
+    if (!config.hubUrl || !config.agentId) {
+        console.warn("Device metadata was saved locally, but no Hub connection is configured.");
+        console.warn("Run `pura-cli connect <hub-ip>:8787 --name <your-name> --background` first.");
+        return;
+    }
+    const result = await waitForAgentVisibility({
+        agentId: config.agentId,
+        hubUrl: config.hubUrl,
+        port: agentPort,
+        serial
+    });
+    if (result.publishedVisible) {
+        console.log("Hub confirmed this device is visible and published.");
+        return;
+    }
+    if (result.deviceVisible) {
+        console.warn("Hub can see this device, but it has not received the published state yet. Refresh the page in a few seconds.");
+        return;
+    }
+    console.warn("The device was published locally, but the Hub does not see it yet.");
+    console.warn(`Make sure the Agent is connected: pura-cli connect ${config.hubUrl} --name "${config.agentName ?? "your name"}" --background`);
+}
+async function waitForAgentVisibility(options) {
+    let localDevices;
+    let hubDevices;
+    let localError = "";
+    let hubError = "";
+    for (const delayMs of [250, 500, 750, 1000, 1500, 2500]) {
+        await sleep(delayMs);
+        try {
+            localDevices = (await fetchJson(`http://127.0.0.1:${options.port}/api/devices`)).devices;
+            localError = "";
+        }
+        catch (error) {
+            localError = error instanceof Error ? error.message : String(error);
+        }
+        try {
+            const allHubDevices = (await fetchJson(`${options.hubUrl}/api/devices`)).devices;
+            hubDevices = allHubDevices.filter((device) => device.agentId === options.agentId);
+            hubError = "";
+        }
+        catch (error) {
+            hubError = error instanceof Error ? error.message : String(error);
+        }
+        const deviceVisible = options.serial ? Boolean(hubDevices?.some((device) => device.remoteSerial === options.serial)) : false;
+        const publishedVisible = options.serial
+            ? Boolean(hubDevices?.some((device) => device.remoteSerial === options.serial && device.publication?.published))
+            : false;
+        if (publishedVisible || deviceVisible) {
+            return { visible: true, deviceVisible, publishedVisible, localDevices, hubDevices, localError, hubError };
+        }
+        if (!options.serial && localDevices && hubDevices && (localDevices.length === 0 || hubDevices.length > 0)) {
+            return { visible: true, deviceVisible, publishedVisible, localDevices, hubDevices, localError, hubError };
+        }
+    }
+    const deviceVisible = options.serial ? Boolean(hubDevices?.some((device) => device.remoteSerial === options.serial)) : false;
+    const publishedVisible = options.serial
+        ? Boolean(hubDevices?.some((device) => device.remoteSerial === options.serial && device.publication?.published))
+        : false;
+    return { visible: false, deviceVisible, publishedVisible, localDevices, hubDevices, localError, hubError };
+}
+async function fetchJson(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(1500) });
+    if (!response.ok) {
+        throw new Error(`${response.status} ${response.statusText}`);
+    }
+    return (await response.json());
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function readFlag(name) {
     const index = args.indexOf(name);
     if (index === -1)