@ardennguyen/zalo-agent-cli 1.0.7

package/src/utils/qr-display.js

@@ -0,0 +1,91 @@
+/**
+ * Cross-platform QR display utility.
+ * Displays Zalo's official QR PNG inline in terminal and saves to file.
+ *
+ * IMPORTANT: Uses Zalo-server-generated PNG (via event.data.image base64),
+ * NOT qrcode-terminal which re-encodes the token text into a different QR
+ * that Zalo app cannot recognize as a login request.
+ *
+ * Display methods:
+ * 1. iTerm2/Kitty/WezTerm inline image (renders PNG directly in terminal)
+ * 2. Save PNG to config dir
+ * 3. Base64 data URL (for IDE/agent preview)
+ * 4. File path with platform-specific open hint
+ */
+
+import { resolve } from "path";
+import { writeFileSync, mkdirSync } from "fs";
+import { platform } from "os";
+import { CONFIG_DIR } from "../core/credentials.js";
+import { info } from "./output.js";
+
+const QR_PATH = resolve(CONFIG_DIR, "qr.png");
+
+/** Get platform-specific command to open a file. */
+function getOpenCommand() {
+    switch (platform()) {
+        case "darwin":
+            return "open";
+        case "win32":
+            return "start";
+        default:
+            return "xdg-open";
+    }
+}
+
+/**
+ * Display QR code from a zca-js login QR event.
+ * Synchronous — safe to call from zca-js callback.
+ * In JSON mode (--json), outputs structured event for AI agents.
+ * @param {object} event - zca-js QR callback event
+ */
+export function displayQR(event) {
+    const imageB64 = event.data?.image || "";
+    const jsonMode = process.env.ZALO_JSON_MODE === "1";
+
+    // Always save PNG to config dir (needed by HTTP server and agents)
+    if (imageB64) {
+        try {
+            mkdirSync(CONFIG_DIR, { recursive: true });
+            writeFileSync(QR_PATH, Buffer.from(imageB64, "base64"));
+        } catch {}
+    }
+
+    // Also fire-and-forget the zca-js built-in save
+    if (event.actions?.saveToFile) {
+        event.actions.saveToFile(QR_PATH).catch(() => {});
+    }
+
+    // JSON mode: structured output for AI agents — no terminal escapes, no noise
+    if (jsonMode) {
+        if (imageB64) {
+            console.log(
+                JSON.stringify({
+                    event: "qr",
+                    image: imageB64,
+                    file: QR_PATH,
+                    dataUrl: `data:image/png;base64,${imageB64}`,
+                }),
+            );
+        }
+        return;
+    }
+
+    // Human mode: terminal inline image + hints
+    if (imageB64) {
+        // iTerm2/Kitty/WezTerm inline image protocol
+        const b64ForTerm = Buffer.from(imageB64, "base64").toString("base64");
+        process.stdout.write(`\x1b]1337;File=inline=1;width=30;preserveAspectRatio=1:${b64ForTerm}\x07\n`);
+
+        const openCmd = getOpenCommand();
+        info(`QR image saved: ${QR_PATH}`);
+        info(`To open: ${openCmd} "${QR_PATH}"`);
+        info("Copy this URL and paste in any browser to view QR:");
+        console.log(`data:image/png;base64,${imageB64}`);
+    }
+}
+
+/** Get the QR image path. */
+export function getQRPath() {
+    return QR_PATH;
+}

package/src/utils/qr-display.test.js

@@ -0,0 +1,97 @@
+/**
+ * Tests for QR display utility — JSON mode structured output for AI agents.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { displayQR, getQRPath } from "./qr-display.js";
+import { existsSync, unlinkSync, mkdirSync } from "fs";
+import { dirname } from "path";
+
+// Tiny valid 1x1 white PNG as base64 (for testing without real QR)
+const TINY_PNG_B64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
+
+describe("displayQR", () => {
+    let originalLog;
+    let captured;
+
+    beforeEach(() => {
+        // Capture console.log output
+        originalLog = console.log;
+        captured = [];
+        console.log = (...args) => captured.push(args.join(" "));
+
+        // Ensure config dir exists for file save
+        const qrDir = dirname(getQRPath());
+        mkdirSync(qrDir, { recursive: true });
+    });
+
+    afterEach(() => {
+        console.log = originalLog;
+        delete process.env.ZALO_JSON_MODE;
+
+        // Clean up saved QR file
+        try {
+            unlinkSync(getQRPath());
+        } catch {}
+    });
+
+    it("JSON mode outputs structured event with all fields", () => {
+        process.env.ZALO_JSON_MODE = "1";
+        displayQR({ data: { image: TINY_PNG_B64 } });
+
+        assert.equal(captured.length, 1, "should output exactly one JSON line");
+        const parsed = JSON.parse(captured[0]);
+        assert.equal(parsed.event, "qr");
+        assert.equal(parsed.image, TINY_PNG_B64);
+        assert.ok(parsed.file.endsWith("qr.png"), "file path should end with qr.png");
+        assert.ok(parsed.dataUrl.startsWith("data:image/png;base64,"), "dataUrl should be a data URL");
+        assert.ok(parsed.dataUrl.includes(TINY_PNG_B64), "dataUrl should contain full base64");
+    });
+
+    it("JSON mode does not output terminal escape sequences", () => {
+        process.env.ZALO_JSON_MODE = "1";
+
+        // Also capture stdout.write
+        const stdoutWrites = [];
+        const originalWrite = process.stdout.write;
+        process.stdout.write = (data) => stdoutWrites.push(data);
+
+        displayQR({ data: { image: TINY_PNG_B64 } });
+
+        process.stdout.write = originalWrite;
+
+        // No iTerm2 escape sequences
+        const hasEscape = stdoutWrites.some((w) => typeof w === "string" && w.includes("\x1b]1337"));
+        assert.ok(!hasEscape, "JSON mode should not output terminal escape sequences");
+    });
+
+    it("saves QR PNG file in both modes", () => {
+        process.env.ZALO_JSON_MODE = "1";
+        displayQR({ data: { image: TINY_PNG_B64 } });
+        assert.ok(existsSync(getQRPath()), "QR PNG should be saved to disk");
+    });
+
+    it("handles empty image gracefully in JSON mode", () => {
+        process.env.ZALO_JSON_MODE = "1";
+        displayQR({ data: {} });
+        assert.equal(captured.length, 0, "should not output anything for empty image");
+    });
+
+    it("human mode outputs data URL with full base64 (not truncated)", () => {
+        // No ZALO_JSON_MODE set = human mode
+        // Suppress stdout.write (terminal escapes)
+        const originalWrite = process.stdout.write;
+        process.stdout.write = () => true;
+
+        displayQR({ data: { image: TINY_PNG_B64 } });
+
+        process.stdout.write = originalWrite;
+
+        // Find the data URL line in captured output
+        const dataUrlLine = captured.find((line) => line.startsWith("data:image/png;base64,"));
+        assert.ok(dataUrlLine, "should output a data URL line");
+        assert.ok(dataUrlLine.includes(TINY_PNG_B64), "data URL should contain full base64, not truncated");
+        assert.ok(!dataUrlLine.includes("..."), "data URL should not be truncated with ...");
+    });
+});

package/src/utils/qr-http-server.js

@@ -0,0 +1,190 @@
+/**
+ * Temporary local HTTP server for QR display on headless/VPS environments.
+ * Serves QR image as a simple HTML page on localhost.
+ * Auto-closes after login completes.
+ */
+
+import http from "http";
+import { readFileSync, existsSync } from "fs";
+import nodefetch from "node-fetch";
+import { info } from "./output.js";
+
+/**
+ * Start a temporary HTTP server that serves the QR image.
+ * @param {string} qrImagePath - path to QR PNG file
+ * @param {number} port - default 18927
+ * @returns {{ url: string, close: () => void }}
+ */
+export function startQrServer(qrImagePath, port = 18927, tryPorts = [18927, 8080, 3000, 9000]) {
+    const server = http.createServer(async (req, res) => {
+        if (req.url === "/qr" || req.url === "/") {
+            if (!existsSync(qrImagePath)) {
+                res.writeHead(200, { "Content-Type": "text/html" });
+                res.end(`<!DOCTYPE html><html><head><meta charset="utf-8">
+<meta http-equiv="refresh" content="2">
+<title>Waiting for QR...</title></head>
+<body style="display:flex;justify-content:center;align-items:center;height:100vh;background:#111;color:#fff;font-family:system-ui">
+<p>QR code generating... auto-refreshing in 2s</p></body></html>`);
+                return;
+            }
+            const img = readFileSync(qrImagePath);
+            const b64 = img.toString("base64");
+            // Embed mascot inline (read from assets if available, else skip)
+            let mascotB64 = "";
+            try {
+                const { resolve: resolvePath } = await import("path");
+                const { fileURLToPath } = await import("url");
+                const { dirname } = await import("path");
+                const dir = dirname(fileURLToPath(import.meta.url));
+                const mascotPath = resolvePath(dir, "../../assets/mascot.png");
+                if (existsSync(mascotPath)) {
+                    mascotB64 = readFileSync(mascotPath).toString("base64");
+                }
+            } catch {}
+            const mascotImg = mascotB64
+                ? `<img src="data:image/png;base64,${mascotB64}" class="mascot" alt="zalo-agent"/>`
+                : "";
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end(`<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>Zalo Agent — QR Login</title>
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<style>
+*{box-sizing:border-box}
+body{display:flex;justify-content:center;align-items:center;min-height:100vh;margin:0;
+  background:linear-gradient(135deg,#0a1628 0%,#111d33 50%,#0d1f3c 100%);font-family:system-ui,-apple-system,sans-serif}
+.card{text-align:center;padding:2.5rem 2rem;background:rgba(17,29,51,0.9);
+  border-radius:20px;max-width:420px;width:90%;
+  border:1px solid rgba(59,130,246,0.2);backdrop-filter:blur(10px);
+  box-shadow:0 20px 60px rgba(0,0,0,0.5),0 0 40px rgba(59,130,246,0.1)}
+.mascot{width:80px;height:80px;border-radius:50%;margin-bottom:0.5rem;
+  border:2px solid rgba(59,130,246,0.4);box-shadow:0 0 20px rgba(59,130,246,0.2)}
+h1{color:#e2e8f0;font-size:1.1rem;font-weight:600;margin:0.5rem 0}
+.brand{color:#3b82f6;font-size:0.8rem;margin-bottom:1.5rem;opacity:0.8}
+.qr-img{width:260px;height:260px;border-radius:12px;border:3px solid rgba(59,130,246,0.3);
+  box-shadow:0 0 30px rgba(59,130,246,0.15)}
+.hint{color:#94a3b8;font-size:0.85rem;margin-top:1.2rem;line-height:1.5}
+.hint strong{color:#60a5fa}
+.success-text{color:#4ade80;font-size:1.3rem;font-weight:bold}
+.hidden{display:none}
+.footer{color:#475569;font-size:0.7rem;margin-top:1.5rem}
+.footer a{color:#3b82f6;text-decoration:none}
+</style></head>
+<body><div class="card">
+<div id="qr-view">
+${mascotImg}
+<h1>Zalo Agent CLI</h1>
+<p class="brand">QR Code Login</p>
+<img src="data:image/png;base64,${b64}" class="qr-img" alt="QR Code"/>
+<p class="hint">Open <strong>Zalo app</strong> > <strong>QR Scanner</strong> to scan</p>
+<p class="footer">Powered by <a href="https://github.com/ardennguyen/zalo-agent-cli">zalo-agent-cli</a></p>
+</div>
+<div id="success-view" class="hidden">
+${mascotImg}
+<h1 style="color:#4ade80;font-size:1.5rem;margin:1rem 0">Login Successful!</h1>
+<p class="success-text">You can close this page now.</p>
+<p class="hint">The CLI is ready to use.</p>
+</div>
+</div>
+<script>
+// Poll /status to detect login success
+setInterval(async()=>{
+  try{
+    const r=await fetch('/status');
+    const d=await r.json();
+    if(d.loggedIn){
+      document.getElementById('qr-view').classList.add('hidden');
+      document.getElementById('success-view').classList.remove('hidden');
+    }
+  }catch{}
+},2000);
+</script>
+</body></html>`);
+        } else if (req.url === "/qr.png") {
+            // Raw PNG image endpoint — for agents to send direct image link
+            if (!existsSync(qrImagePath)) {
+                res.writeHead(404, { "Content-Type": "text/plain" });
+                res.end("QR not generated yet");
+                return;
+            }
+            const img = readFileSync(qrImagePath);
+            res.writeHead(200, {
+                "Content-Type": "image/png",
+                "Content-Length": img.length,
+                "Cache-Control": "no-cache, no-store",
+            });
+            res.end(img);
+        } else if (req.url === "/status") {
+            // Login status endpoint for browser polling
+            let loggedIn = false;
+            try {
+                const { isLoggedIn } = await import("../core/zalo-client.js");
+                loggedIn = isLoggedIn();
+            } catch {}
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ loggedIn }));
+        } else {
+            res.writeHead(404);
+            res.end("Not found");
+        }
+    });
+
+    // Try ports in order until one works (avoids firewall issues)
+    let currentPortIdx = 0;
+
+    function tryListen() {
+        const p = tryPorts[currentPortIdx];
+        server.listen(p, "0.0.0.0");
+    }
+
+    server.on("listening", async () => {
+        const actualPort = server.address().port;
+        const jsonMode = process.env.ZALO_JSON_MODE === "1";
+        let publicIp = null;
+
+        // Auto-detect public IP for VPS users
+        try {
+            const res = await nodefetch("https://api.ipify.org", { timeout: 3000 });
+            publicIp = (await res.text()).trim() || null;
+        } catch {}
+
+        if (jsonMode) {
+            console.log(
+                JSON.stringify({
+                    event: "qr_server",
+                    port: actualPort,
+                    localUrl: `http://localhost:${actualPort}/qr`,
+                    imageUrl: `http://localhost:${actualPort}/qr.png`,
+                    publicUrl: publicIp ? `http://${publicIp}:${actualPort}/qr` : null,
+                    publicImageUrl: publicIp ? `http://${publicIp}:${actualPort}/qr.png` : null,
+                }),
+            );
+        } else {
+            info(`QR available at: http://localhost:${actualPort}/qr`);
+            if (publicIp) info(`On VPS, open: http://${publicIp}:${actualPort}/qr`);
+            else info(`On VPS, open: http://<your-server-ip>:${actualPort}/qr`);
+            info(`If firewall blocks, run: sudo ufw allow ${actualPort}/tcp`);
+            info(`Or copy QR file: scp user@vps:~/.zalo-agent/qr.png ./qr.png`);
+        }
+    });
+
+    server.on("error", (err) => {
+        if (err.code === "EADDRINUSE" || err.code === "EACCES") {
+            currentPortIdx++;
+            if (currentPortIdx < tryPorts.length) {
+                info(`Port ${tryPorts[currentPortIdx - 1]} unavailable, trying ${tryPorts[currentPortIdx]}...`);
+                tryListen();
+            }
+        }
+    });
+
+    tryListen();
+
+    return {
+        url: `http://localhost:${port}/qr`,
+        close: () => {
+            try {
+                server.close();
+            } catch {}
+        },
+    };
+}

package/src/utils/update-check.js

@@ -0,0 +1,56 @@
+/**
+ * Non-blocking update check — warns user if a newer version is available on npm.
+ * Runs silently in background; never blocks CLI execution.
+ */
+
+import { execSync } from "node:child_process";
+import { warning } from "./output.js";
+
+/**
+ * Check npm registry for the latest version, warn if outdated.
+ * Uses "npm view @ardennguyen/zalo-agent-cli version" to fetch from the npm registry.
+ *
+ * Skipped automatically when stdout is piped (e.g. tests, scripts, JSON mode, MCP).
+ *
+ * @param {string} currentVersion - Current package version (from package.json)
+ * @param {boolean} jsonMode - Suppress output in JSON mode
+ */
+export function checkForUpdates(currentVersion, jsonMode) {
+    if (jsonMode) return;
+    if (!process.stdout.isTTY) return; // skip in piped / scripted mode
+    if (process.env.ZALO_AGENT_NO_UPDATE_CHECK) return; // explicit opt-out
+
+    try {
+        const latest = execSync("npm view @ardennguyen/zalo-agent-cli version", {
+            encoding: "utf8",
+            timeout: 5000,
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
+        }).trim();
+
+        if (latest && latest !== currentVersion) {
+            warning(
+                `Update available: ${currentVersion} → ${latest}. Run: npm install -g @ardennguyen/zalo-agent-cli@latest`,
+            );
+        }
+    } catch {
+        // Silent failure — network issues shouldn't block CLI usage
+    }
+}
+
+/**
+ * Self-update by re-installing the latest version from npm registry.
+ * @returns {boolean} success
+ */
+export function selfUpdate() {
+    try {
+        execSync("npm install -g @ardennguyen/zalo-agent-cli@latest", {
+            encoding: "utf8",
+            stdio: "inherit",
+            timeout: 60000,
+        });
+        return true;
+    } catch {
+        return false;
+    }
+}