zalo-agent-cli 1.1.0 → 1.3.0

package/src/mcp/notifier.test.js

@@ -0,0 +1,239 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ZaloNotifier } from "./notifier.js";
+
+/** Create a spy api.sendMessage that records calls */
+function makeSpy() {
+    const calls = [];
+    const api = {
+        sendMessage: async (text, thread, type) => {
+            calls.push({ text, thread, type });
+        },
+    };
+    return { api, calls };
+}
+
+/** Minimal enabled config for ZaloNotifier */
+function enabledConfig(overrides = {}) {
+    return {
+        notify: {
+            enabled: true,
+            thread: "notify_group_123",
+            on: ["dm"],
+            cooldown: "10ms", // very short for tests
+            ...overrides,
+        },
+    };
+}
+
+/** Disabled config */
+function disabledConfig() {
+    return {
+        notify: {
+            enabled: false,
+            thread: "notify_group_123",
+            on: ["dm"],
+            cooldown: "10ms",
+        },
+    };
+}
+
+/** A normalised DM message */
+function dmMsg(text = "hello", overrides = {}) {
+    return { threadType: "dm", senderId: "user_1", senderName: "Alice", text, ...overrides };
+}
+
+/** Wait for ms milliseconds */
+function wait(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+
+describe("ZaloNotifier constructor", () => {
+    it("is disabled by default when config.notify.enabled=false", () => {
+        const { api } = makeSpy();
+        const n = new ZaloNotifier(api, disabledConfig());
+        assert.equal(n._enabled, false);
+    });
+
+    it("is enabled when config.notify.enabled=true", () => {
+        const { api } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        assert.equal(n._enabled, true);
+    });
+
+    it("stores notify thread and onTypes from config", () => {
+        const { api } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig({ thread: "grp_99", on: ["dm", "group"] }));
+        assert.equal(n._notifyThread, "grp_99");
+        assert.ok(n._onTypes.has("dm"));
+        assert.ok(n._onTypes.has("group"));
+    });
+
+    it("agentConnected starts as false", () => {
+        const { api } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        assert.equal(n._agentConnected, false);
+    });
+});
+
+describe("ZaloNotifier onMessage - disabled", () => {
+    it("does not queue messages when disabled", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, disabledConfig());
+        n.onMessage(dmMsg());
+        await wait(30);
+        assert.equal(calls.length, 0);
+        assert.equal(n._pending.length, 0);
+        n.destroy();
+    });
+});
+
+describe("ZaloNotifier onMessage - agent connected", () => {
+    it("does not notify when agent is connected", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        n.setAgentConnected(true);
+        n.onMessage(dmMsg());
+        await wait(30);
+        assert.equal(calls.length, 0);
+        n.destroy();
+    });
+
+    it("notifies again after agent disconnects", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        n.setAgentConnected(true);
+        n.onMessage(dmMsg("ignored"));
+        n.setAgentConnected(false);
+        n.onMessage(dmMsg("should notify"));
+        await wait(30);
+        assert.equal(calls.length, 1);
+        n.destroy();
+    });
+});
+
+describe("ZaloNotifier onMessage - type filtering", () => {
+    it("queues messages matching onTypes (dm)", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig({ on: ["dm"] }));
+        n.onMessage(dmMsg("queued"));
+        await wait(30);
+        assert.equal(calls.length, 1);
+    });
+
+    it("ignores messages not matching onTypes", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig({ on: ["dm"] }));
+        n.onMessage({ threadType: "group", senderId: "u1", senderName: "Bob", text: "hi" });
+        await wait(30);
+        assert.equal(calls.length, 0);
+    });
+
+    it("notifies for group type when configured", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig({ on: ["group"] }));
+        n.onMessage({ threadType: "group", senderId: "u1", senderName: "Bob", text: "hi" });
+        await wait(30);
+        assert.equal(calls.length, 1);
+    });
+});
+
+describe("ZaloNotifier _flush notification format", () => {
+    it("sends to the configured notify thread", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig({ thread: "grp_notify" }));
+        n.onMessage(dmMsg("test message"));
+        await wait(30);
+        assert.equal(calls[0].thread, "grp_notify");
+        assert.equal(calls[0].type, 1); // Group conversation type
+    });
+
+    it("notification text includes sender name and message preview", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        n.onMessage(dmMsg("hello world", { senderName: "Alice" }));
+        await wait(30);
+        assert.ok(calls[0].text.includes("Alice"));
+        assert.ok(calls[0].text.includes("hello world"));
+    });
+
+    it("shows up to 3 message previews in a single flush", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        n.onMessage(dmMsg("msg1", { senderName: "A" }));
+        n.onMessage(dmMsg("msg2", { senderName: "B" }));
+        n.onMessage(dmMsg("msg3", { senderName: "C" }));
+        await wait(30);
+        // Only one batched send
+        assert.equal(calls.length, 1);
+        assert.ok(calls[0].text.includes("msg1"));
+        assert.ok(calls[0].text.includes("msg2"));
+        assert.ok(calls[0].text.includes("msg3"));
+    });
+
+    it("includes overflow count when more than 3 messages", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        for (let i = 1; i <= 5; i++) {
+            n.onMessage(dmMsg(`msg${i}`, { senderName: `User${i}` }));
+        }
+        await wait(30);
+        assert.equal(calls.length, 1);
+        // Should mention the extra 2 messages
+        assert.ok(calls[0].text.includes("2"));
+    });
+
+    it("sends total message count in notification text", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        n.onMessage(dmMsg("one"));
+        n.onMessage(dmMsg("two"));
+        await wait(30);
+        assert.ok(calls[0].text.includes("2"));
+    });
+});
+
+describe("ZaloNotifier cooldown batching", () => {
+    it("batches multiple messages within cooldown into a single send", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig({ cooldown: "20ms" }));
+        n.onMessage(dmMsg("first"));
+        n.onMessage(dmMsg("second"));
+        n.onMessage(dmMsg("third"));
+        await wait(50); // wait for cooldown to fire
+        assert.equal(calls.length, 1);
+    });
+
+    it("clears pending after flush so next batch is independent", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig({ cooldown: "20ms" }));
+        n.onMessage(dmMsg("batch1"));
+        await wait(40); // first flush
+
+        n.onMessage(dmMsg("batch2"));
+        await wait(40); // second flush
+
+        assert.equal(calls.length, 2);
+    });
+});
+
+describe("ZaloNotifier destroy", () => {
+    it("flushes pending messages on destroy", async () => {
+        const { api, calls } = makeSpy();
+        // Long cooldown so timer wouldn't fire naturally
+        const n = new ZaloNotifier(api, enabledConfig({ cooldown: "60000ms" }));
+        n.onMessage(dmMsg("urgent"));
+        n.destroy(); // should flush immediately
+        // _flush is async, give it a tick
+        await wait(10);
+        assert.equal(calls.length, 1);
+    });
+
+    it("destroy with no pending messages does not send", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        n.destroy(); // nothing pending, no timer
+        await wait(10);
+        assert.equal(calls.length, 0);
+    });
+});

package/src/mcp/thread-filter.js

@@ -0,0 +1,79 @@
+/**
+ * Filter which threads to watch and which messages to keep.
+ * Supports glob-like patterns for thread matching and noise reduction.
+ */
+
+/** System message types to drop (join, leave, pin, etc.) */
+const SYSTEM_MSG_TYPES = new Set(["system", "join", "leave", "pin", "unpin", "rename"]);
+
+export class ThreadFilter {
+    /**
+     * @param {object} config - MCP config object
+     * @param {string[]} config.watchThreads - Glob patterns like ["dm:*", "group:support"]
+     * @param {string[]} [config.triggerKeywords] - Keywords that trigger attention
+     */
+    constructor(config) {
+        this._watchPatterns = config.watchThreads || ["dm:*", "group:*"];
+        this._triggerKeywords = (config.triggerKeywords || []).map((k) => k.toLowerCase());
+    }
+
+    /**
+     * Check if a thread should be watched based on patterns.
+     * Pattern format: "dm:*", "group:*", "group:exact_id", "dm:exact_id"
+     * @param {string} threadId
+     * @param {"group"|"dm"} threadType
+     * @returns {boolean}
+     */
+    shouldWatch(threadId, threadType) {
+        const key = `${threadType}:${threadId}`;
+        for (const pattern of this._watchPatterns) {
+            if (this._matchPattern(pattern, key, threadType)) return true;
+        }
+        return false;
+    }
+
+    /**
+     * Check if a message passes noise filter (drop stickers, short emoji, system msgs).
+     * @param {object} message - Normalized message
+     * @returns {boolean}
+     */
+    shouldKeep(message) {
+        // Drop system messages
+        if (message.type && SYSTEM_MSG_TYPES.has(message.type)) return false;
+        // Drop sticker-only messages
+        if (message.type === "sticker") return false;
+        // Drop very short emoji-only messages (< 3 chars, all emoji/whitespace)
+        if (message.text && message.text.length < 3 && /^[\s\p{Emoji}]*$/u.test(message.text)) {
+            return false;
+        }
+        // Keep everything else (including images, files, links)
+        return true;
+    }
+
+    /**
+     * Check if a message is a trigger (contains keyword or @mention).
+     * @param {object} message - Normalized message
+     * @returns {boolean}
+     */
+    isTrigger(message) {
+        if (!message.text || this._triggerKeywords.length === 0) return false;
+        const lower = message.text.toLowerCase();
+        return this._triggerKeywords.some((kw) => lower.includes(kw));
+    }
+
+    /**
+     * Match a pattern against a thread key.
+     * @param {string} pattern - e.g. "dm:*", "group:support_123"
+     * @param {string} key - e.g. "dm:user_456", "group:support_123"
+     * @param {string} threadType - "dm" or "group"
+     * @returns {boolean}
+     */
+    _matchPattern(pattern, key, threadType) {
+        // Wildcard: "dm:*" matches all DMs, "group:*" matches all groups
+        if (pattern === `${threadType}:*`) return true;
+        // Catch-all patterns
+        if (pattern === "*" || pattern === "*:*") return true;
+        // Exact match
+        return pattern === key;
+    }
+}

package/src/mcp/thread-filter.test.js

@@ -0,0 +1,206 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ThreadFilter } from "./thread-filter.js";
+
+/** Helper: create a ThreadFilter with given patterns and keywords */
+function makeFilter(watchThreads = ["dm:*", "group:*"], triggerKeywords = []) {
+    return new ThreadFilter({ watchThreads, triggerKeywords });
+}
+
+describe("ThreadFilter shouldWatch - glob patterns", () => {
+    it("dm:* matches any DM thread", () => {
+        const f = makeFilter(["dm:*"]);
+        assert.equal(f.shouldWatch("user_123", "dm"), true);
+        assert.equal(f.shouldWatch("abc", "dm"), true);
+    });
+
+    it("group:* matches any group thread", () => {
+        const f = makeFilter(["group:*"]);
+        assert.equal(f.shouldWatch("support_456", "group"), true);
+        assert.equal(f.shouldWatch("anything", "group"), true);
+    });
+
+    it("dm:* does not match group threads", () => {
+        const f = makeFilter(["dm:*"]);
+        assert.equal(f.shouldWatch("some_group", "group"), false);
+    });
+
+    it("group:* does not match dm threads", () => {
+        const f = makeFilter(["group:*"]);
+        assert.equal(f.shouldWatch("some_user", "dm"), false);
+    });
+});
+
+describe("ThreadFilter shouldWatch - exact match", () => {
+    it("exact group pattern matches only that thread id", () => {
+        const f = makeFilter(["group:support_123"]);
+        assert.equal(f.shouldWatch("support_123", "group"), true);
+        assert.equal(f.shouldWatch("support_456", "group"), false);
+    });
+
+    it("exact dm pattern matches only that thread id", () => {
+        const f = makeFilter(["dm:user_42"]);
+        assert.equal(f.shouldWatch("user_42", "dm"), true);
+        assert.equal(f.shouldWatch("user_99", "dm"), false);
+    });
+
+    it("exact match requires type prefix to align", () => {
+        const f = makeFilter(["group:support_123"]);
+        // same id but different type should not match
+        assert.equal(f.shouldWatch("support_123", "dm"), false);
+    });
+});
+
+describe("ThreadFilter shouldWatch - catch-all patterns", () => {
+    it("* matches any thread regardless of type", () => {
+        const f = makeFilter(["*"]);
+        assert.equal(f.shouldWatch("user_1", "dm"), true);
+        assert.equal(f.shouldWatch("group_1", "group"), true);
+    });
+
+    it("*:* matches any thread regardless of type", () => {
+        const f = makeFilter(["*:*"]);
+        assert.equal(f.shouldWatch("user_1", "dm"), true);
+        assert.equal(f.shouldWatch("group_1", "group"), true);
+    });
+});
+
+describe("ThreadFilter shouldWatch - unmatched patterns", () => {
+    it("returns false when no pattern matches", () => {
+        const f = makeFilter(["group:specific_only"]);
+        assert.equal(f.shouldWatch("other_group", "group"), false);
+        assert.equal(f.shouldWatch("any_user", "dm"), false);
+    });
+
+    it("empty watchThreads array never matches", () => {
+        const f = makeFilter([]);
+        assert.equal(f.shouldWatch("x", "dm"), false);
+        assert.equal(f.shouldWatch("y", "group"), false);
+    });
+});
+
+describe("ThreadFilter shouldKeep - system messages dropped", () => {
+    const SYSTEM_TYPES = ["system", "join", "leave", "pin", "unpin", "rename"];
+
+    for (const type of SYSTEM_TYPES) {
+        it(`drops message with type="${type}"`, () => {
+            const f = makeFilter();
+            assert.equal(f.shouldKeep({ type, text: "some text" }), false);
+        });
+    }
+});
+
+describe("ThreadFilter shouldKeep - sticker messages dropped", () => {
+    it("drops sticker-only messages", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ type: "sticker" }), false);
+    });
+});
+
+describe("ThreadFilter shouldKeep - short emoji-only messages dropped", () => {
+    it("drops single emoji (< 3 chars)", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ text: "👍" }), false);
+    });
+
+    it("drops two-char emoji message", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ text: "😂" }), false);
+    });
+
+    it("keeps messages with 3+ chars even if emoji", () => {
+        const f = makeFilter();
+        // Three emojis — length in JS may vary; use text that is clearly >= 3 code units
+        assert.equal(f.shouldKeep({ text: "hey" }), true);
+    });
+
+    it("drops whitespace-only short message", () => {
+        const f = makeFilter();
+        // 1-2 spaces are < 3 chars and match /^[\s\p{Emoji}]*$/u
+        assert.equal(f.shouldKeep({ text: " " }), false);
+    });
+});
+
+describe("ThreadFilter shouldKeep - kept messages", () => {
+    it("keeps normal text messages", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ type: "text", text: "Hello there!" }), true);
+    });
+
+    it("keeps image messages (no text)", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ type: "image" }), true);
+    });
+
+    it("keeps file messages", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ type: "file" }), true);
+    });
+
+    it("keeps link messages", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ type: "link", text: "https://example.com" }), true);
+    });
+
+    it("keeps message with no type field", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ text: "plain message" }), true);
+    });
+});
+
+describe("ThreadFilter isTrigger", () => {
+    it("detects keyword in message text (case-insensitive)", () => {
+        const f = makeFilter(["dm:*"], ["@bot"]);
+        assert.equal(f.isTrigger({ text: "Hey @BOT help me" }), true);
+    });
+
+    it("detects keyword at start of text", () => {
+        const f = makeFilter(["dm:*"], ["help"]);
+        assert.equal(f.isTrigger({ text: "help me please" }), true);
+    });
+
+    it("returns false when keyword not present", () => {
+        const f = makeFilter(["dm:*"], ["@bot"]);
+        assert.equal(f.isTrigger({ text: "just a normal message" }), false);
+    });
+
+    it("returns false when no keywords configured", () => {
+        const f = makeFilter(["dm:*"], []);
+        assert.equal(f.isTrigger({ text: "@bot trigger me" }), false);
+    });
+
+    it("returns false when text is empty string", () => {
+        const f = makeFilter(["dm:*"], ["@bot"]);
+        assert.equal(f.isTrigger({ text: "" }), false);
+    });
+
+    it("returns false when text property is missing", () => {
+        const f = makeFilter(["dm:*"], ["@bot"]);
+        assert.equal(f.isTrigger({}), false);
+    });
+
+    it("matches any of multiple keywords", () => {
+        const f = makeFilter(["dm:*"], ["urgent", "help", "broken"]);
+        assert.equal(f.isTrigger({ text: "system is broken" }), true);
+        assert.equal(f.isTrigger({ text: "need urgent attention" }), true);
+        assert.equal(f.isTrigger({ text: "everything is fine" }), false);
+    });
+});
+
+describe("ThreadFilter edge cases", () => {
+    it("shouldKeep handles empty message object", () => {
+        const f = makeFilter();
+        // No type, no text — should keep (default allow)
+        assert.equal(f.shouldKeep({}), true);
+    });
+
+    it("shouldKeep handles null text field gracefully", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ type: "text", text: null }), true);
+    });
+
+    it("isTrigger handles null text field", () => {
+        const f = makeFilter(["dm:*"], ["keyword"]);
+        assert.equal(f.isTrigger({ text: null }), false);
+    });
+});

package/src/utils/qr-display.js

@@ -36,39 +36,50 @@ function getOpenCommand() {
 /**
  * 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";
 
-    // 1. Display Zalo's official QR PNG inline in terminal
-    // Uses iTerm2 inline image protocol (also WezTerm, Hyper, Kitty)
-    // Terminals that don't support it simply ignore the escape sequence
-    if (imageB64) {
-        const b64ForTerm = Buffer.from(imageB64, "base64").toString("base64");
-        process.stdout.write(`\x1b]1337;File=inline=1;width=30;preserveAspectRatio=1:${b64ForTerm}\x07\n`);
-    }
-
-    // 2. Save PNG to config dir
+    // 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"));
-            const openCmd = getOpenCommand();
-            info(`QR image saved: ${QR_PATH}`);
-            info(`To open: ${openCmd} "${QR_PATH}"`);
         } catch {}
     }
 
-    // 3. Also fire-and-forget the zca-js built-in save
+    // Also fire-and-forget the zca-js built-in save
     if (event.actions?.saveToFile) {
         event.actions.saveToFile(QR_PATH).catch(() => {});
     }
 
-    // 4. Base64 data URL (for coding agents / IDE preview)
+    // 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) {
-        info("QR data URL (for IDE preview):");
-        console.log(`  data:image/png;base64,${imageB64.substring(0, 100)}...`);
+        // 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}`);
     }
 }
 

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

@@ -0,0 +1,98 @@
+/**
+ * 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 ...");
+    });
+});