@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/commands/msg-media.js

@@ -0,0 +1,187 @@
+/**
+ * `msg media <msgId>`: a cached photo, voice message, video or file, decrypted for the person at the keyboard. The
+ * cache itself stays encrypted (src/core/keystore/media-seal.js); this is the CLI's twin of `zalo_view_media`.
+ *
+ * - `--out <file>`: the plaintext written to a file the user names (0600).
+ * - `--stdout`: the plaintext bytes on standard output (for a pipe).
+ * - `--deliver tempfile` (the default): a private decrypted copy under `<config-dir>/tmp/media/`, deleted after
+ *   `media.tempfileTtl` (10 minutes) by a running daemon's sweep or the next command's.
+ * - `--deliver link`: a link the running `listen` / `mcp start` daemon serves (`/zalo/media/<token>`, 10 minutes),
+ *   asked over its loopback channel; without a daemon there is no one to serve it.
+ * - `--deliver inline`: the bytes as base64 in the `--json` reply (pictures and voice up to `inlineMaxBytes`).
+ * - `--open`: a tempfile, opened with this machine's viewer.
+ *
+ * It reads the cache only (no login). A message in a hidden chat is refused, as `msg search` leaves those chats out.
+ */
+import { closeSync, openSync } from "node:fs";
+import { getActive } from "../core/accounts.js";
+import { getAccountDbPath, getAccountDir } from "../core/credentials.js";
+import { getMessageForAction, initDb } from "../core/db.js";
+import { mediaLinkViaDaemon } from "../core/daemon-channel.js";
+import { resolveMediaDelivery } from "../core/deploy-policy.js";
+import { hiddenChatsFor } from "../core/hidden-chats.js";
+import { scopeOfDir } from "../core/keystore/keyring.js";
+import { decryptMediaToFile, mediaFileState, openMedia } from "../core/keystore/media-seal.js";
+import { INLINE_KINDS, deliverCachedMedia, mediaInfo } from "../core/media-deliver.js";
+import { openFile } from "../utils/open-file.js";
+import { error, info, output, success } from "../utils/output.js";
+
+const MODES = ["inline", "link", "tempfile"];
+
+/**
+ * Register `msg media` on the `msg` group.
+ *
+ * @param {import("commander").Command} msg
+ * @param {import("commander").Command} program
+ * @returns {import("commander").Command}
+ */
+export function registerMsgMedia(msg, program) {
+    const cmd = msg
+        .command("media <msgId>")
+        .description(
+            "Get a cached photo, voice message, video or file, decrypted: a private temporary copy (default), a file (--out), stdout (--stdout) or a link from the running daemon (--deliver link)",
+        )
+        .option("--out <file>", "Write the decrypted media to this file")
+        .option("--stdout", "Write the decrypted bytes to standard output")
+        .option("--deliver <mode>", "tempfile (default), link (needs a running listen / mcp start) or inline (--json)")
+        .option("--open", "Open it with this machine's viewer (a temporary copy)")
+        .action(async (msgId, opts) => {
+            const jsonMode = program.opts().json;
+            const fail = (message) => {
+                error(message);
+                process.exit(1);
+            };
+            const picked = [
+                opts.out ? "--out" : null,
+                opts.stdout ? "--stdout" : null,
+                opts.deliver ? "--deliver" : null,
+            ];
+            if (picked.filter(Boolean).length > 1) fail(`Choose one of ${picked.filter(Boolean).join(", ")}.`);
+            const mode = opts.deliver ? String(opts.deliver).trim().toLowerCase() : null;
+            if (mode && !MODES.includes(mode)) fail(`--deliver is one of ${MODES.join(", ")}.`);
+            if (opts.open && (opts.out || opts.stdout || (mode && mode !== "tempfile"))) {
+                fail("--open opens a temporary copy: use it alone or with --deliver tempfile.");
+            }
+            const account = getActive();
+            if (!account) fail("No active account. Please login first.");
+            const accountDir = getAccountDir(account.ownId);
+            let row;
+            try {
+                initDb(getAccountDbPath(account.ownId));
+                row = getMessageForAction(String(msgId));
+            } catch (e) {
+                fail(e?.code === "ROW_MAC" ? e.message : `The local cache could not be opened: ${e.message}`);
+            }
+            if (!row) fail(`Message ${msgId} is not in the local cache.`);
+            if (hiddenChatsFor(account.ownId, { stateDir: accountDir }).isHidden(row.threadId)) {
+                fail("That message is in a hidden chat, which this command leaves out (as msg search does).");
+            }
+            if (!row.localPath || mediaFileState(row.localPath) === "absent") {
+                fail(
+                    `Message ${msgId} has no downloaded media. Fetch it first:  zalo-agent sync-media -T ${row.threadId}`,
+                );
+            }
+            const scope = scopeOfDir(accountDir);
+            const base = { msgId: row.msgId, threadId: row.threadId, mediaType: row.type || null };
+
+            try {
+                if (opts.stdout) {
+                    const m = openMedia(row.localPath, scope, { msgId: row.msgId });
+                    await new Promise((resolve, reject) => {
+                        const s = m.stream();
+                        s.on("error", reject);
+                        process.stdout.on("error", reject);
+                        s.on("end", resolve);
+                        s.pipe(process.stdout, { end: false });
+                    });
+                    return;
+                }
+                if (opts.out) {
+                    // Created 0600 before a byte is written: the plaintext is the user's to keep, not the world's.
+                    closeSync(openSync(opts.out, "w", 0o600));
+                    const written = decryptMediaToFile(row.localPath, opts.out, scope, { msgId: row.msgId });
+                    return output({ ...base, delivery: "file", path: opts.out, size: written }, jsonMode, () =>
+                        success(`Wrote ${written} bytes to ${opts.out}`),
+                    );
+                }
+                if (mode === "link") {
+                    const got = await mediaLinkViaDaemon(accountDir, { msgId: row.msgId });
+                    if (!got) {
+                        fail(
+                            "A link is served by a running daemon, and none is running for this account. Start `zalo-agent listen` or `zalo-agent mcp start`, or use --out / the default tempfile.",
+                        );
+                    }
+                    if (!got.ok) fail(`The daemon could not hand out a link: ${got.error}`);
+                    const reply = {
+                        ...base,
+                        delivery: "link",
+                        ...got,
+                        expiresAt: new Date(got.expiresAt).toISOString(),
+                    };
+                    delete reply.ok;
+                    return output(reply, jsonMode, () => {
+                        success(got.url);
+                        info(
+                            `Works until ${new Date(got.expiresAt).toLocaleString()}${got.auth === "bearer" ? ", with the server's bearer token" : ""}.`,
+                        );
+                    });
+                }
+                const policy = resolveMediaDelivery({ accountId: account.ownId });
+                const meta = mediaInfo(row.localPath);
+                if (mode === "inline") {
+                    if (!jsonMode) fail("--deliver inline prints base64 in the --json reply; for a file use --out.");
+                    if (!INLINE_KINDS[row.type] || meta.size > policy.inlineMaxBytes) {
+                        fail(
+                            `Only pictures and voice up to ${policy.inlineMaxBytes} bytes go inline; use --out or the default tempfile.`,
+                        );
+                    }
+                }
+                const out = await deliverCachedMedia({
+                    mode: mode || "tempfile",
+                    file: row.localPath,
+                    scope,
+                    msgId: row.msgId,
+                    threadId: row.threadId,
+                    accountId: account.ownId,
+                    info: meta,
+                    policy,
+                    // This process exits now: the copy outlives it and a sweep removes it after the TTL.
+                    keepOnExit: true,
+                });
+                if (out.mode === "inline") {
+                    return output(
+                        {
+                            ...base,
+                            delivery: "inline",
+                            mimeType: out.mimeType,
+                            size: out.size,
+                            data: out.bytes.toString("base64"),
+                        },
+                        true,
+                    );
+                }
+                if (opts.open) openFile(out.path);
+                return output(
+                    {
+                        ...base,
+                        delivery: "tempfile",
+                        path: out.path,
+                        mimeType: out.mimeType,
+                        size: out.size,
+                        expiresAt: new Date(out.expiresAt).toISOString(),
+                        opened: Boolean(opts.open),
+                    },
+                    jsonMode,
+                    () => {
+                        success(out.path);
+                        info(`A private decrypted copy, deleted after ${new Date(out.expiresAt).toLocaleString()}.`);
+                    },
+                );
+            } catch (e) {
+                fail(`The media could not be read: ${e.message}`);
+            }
+        });
+    // The preAction hook logs in before most commands. This one reads the cache and nothing else.
+    cmd.zaloLocalOnly = true;
+    return cmd;
+}

package/src/commands/msg-search.js

@@ -0,0 +1,219 @@
+/**
+ * `msg search`: search the local message cache (plan items F4, F6, F7, F9).
+ *
+ * Local only: it reads `zalo.db` and never contacts Zalo, so it needs no login and works offline. What it can find is
+ * what the cache holds; the coverage line under the results says how far back that goes and what to run to extend it.
+ */
+import chalk from "chalk";
+import { getActive } from "../core/accounts.js";
+import { getAccountDbPath, getAccountDir } from "../core/credentials.js";
+import { hiddenChatsFor } from "../core/hidden-chats.js";
+import { configureSearchIndex, getThreadNames, initDb } from "../core/db.js";
+import { senderNameFields } from "../core/contact-names.js";
+import { MAX_CONTEXT, searchPage } from "../core/search.js";
+import { parseDateBound, parsePeriod } from "../utils/date-range.js";
+import { error, info, output } from "../utils/output.js";
+import { parseIntAtLeast } from "../utils/parse-options.js";
+
+/**
+ * The search options a person typed, as the filters of a query.
+ *
+ * @param {object} opts - the parsed command options
+ * @param {string} ownId - the active account, for `--from me`
+ * @param {number} [now]
+ * @returns {{threadId?: string, senderId?: string, since?: number, until?: number}}
+ * @throws {Error} for a date or period that is not one
+ */
+export function filtersFromOptions(opts, ownId, now = Date.now()) {
+    const out = {};
+    if (opts.thread) out.threadId = String(opts.thread);
+    if (opts.from) out.senderId = String(opts.from).toLowerCase() === "me" ? String(ownId) : String(opts.from);
+    // --last is a shorthand for --since, and the more specific of the two when both are given.
+    if (opts.last) out.since = parsePeriod(opts.last, now);
+    else if (opts.since) out.since = parseDateBound(opts.since, "start");
+    if (opts.until) out.until = parseDateBound(opts.until, "end");
+    if (out.since !== undefined && out.until !== undefined && out.since > out.until) {
+        throw new Error("--since is after --until: nothing can be in between.");
+    }
+    return out;
+}
+
+/**
+ * A reporter for the first search's preparation of the index: says what it is doing, then how far it is, at most every
+ * 20%, so a one-time wait of a minute on a big cache is not silent.
+ *
+ * @param {(line: string) => void} write
+ * @returns {(p: {phase: string, done: number, total: number|null}) => void}
+ */
+export function indexProgressReporter(write) {
+    let announced = false;
+    let lastStep = 0;
+    let lastPhase = null;
+    const words = { fold: "reading the messages", index: "building the index" };
+    return ({ phase, done, total }) => {
+        if (!announced) {
+            announced = true;
+            write("Preparing the search index (done once; the next search is quick)...");
+        }
+        if (phase !== lastPhase) {
+            // Each phase counts its own fifths.
+            lastPhase = phase;
+            lastStep = 0;
+        }
+        if (!total) return;
+        const step = Math.floor((done / total) * 5);
+        if (step > lastStep) {
+            lastStep = step;
+            write(`  ${words[phase] ?? phase}: ${Math.min(100, step * 20)}% (${done} of ${total})`);
+        }
+    };
+}
+
+/** A hit as the JSON output and the MCP tool show it. */
+export function hitToJson(hit, threadNames) {
+    const r = hit.row;
+    const lite = (m) => ({
+        msgId: m.msgId,
+        senderId: m.senderId,
+        ...senderNameFields(m.senderId, m.senderName),
+        text: m.text,
+        timestamp: m.timestamp,
+        type: m.type,
+    });
+    return {
+        msgId: r.msgId,
+        threadId: r.threadId,
+        threadName: threadNames.get(String(r.threadId))?.name ?? null,
+        senderId: r.senderId,
+        // Alias first (src/core/contact-names.js); `senderZaloName` is the name the message carried.
+        ...senderNameFields(r.senderId, r.senderName),
+        text: r.text,
+        snippet: hit.snippet,
+        timestamp: r.timestamp,
+        type: r.type,
+        hasAttachment: Boolean(r.has_attachment),
+        mediaCached: Boolean(r.localPath),
+        ...(hit.context && { context: { before: hit.context.before.map(lite), after: hit.context.after.map(lite) } }),
+    };
+}
+
+/** One hit, as a block of the human output: the messages before it, the hit with its match marked, the ones after. */
+function printHit(h) {
+    const when = h.timestamp ? new Date(h.timestamp).toLocaleString() : "?";
+    const s = h.snippet;
+    const shown =
+        s.matchStart === null
+            ? s.text
+            : s.text.slice(0, s.matchStart) +
+              chalk.bold.yellow(s.text.slice(s.matchStart, s.matchEnd)) +
+              s.text.slice(s.matchEnd);
+    const where = h.threadName ?? h.threadId;
+    const who = h.senderName ?? h.senderId;
+    const tag = h.type && h.type !== "text" ? chalk.dim(` [${h.type}]`) : "";
+    const around = (m) =>
+        chalk.dim(
+            `      ${new Date(m.timestamp).toLocaleTimeString()} ${m.senderName ?? m.senderId}: ` +
+                String(m.text ?? "")
+                    .replace(/s+/g, " ")
+                    .slice(0, 100),
+        );
+    for (const m of h.context?.before ?? []) console.log(around(m));
+    console.log(`${chalk.dim(when)}  ${chalk.cyan(where)}  ${who}${tag}
+  ${shown}  ${chalk.dim(`(${h.msgId})`)}`);
+    for (const m of h.context?.after ?? []) console.log(around(m));
+    if (h.context) console.log();
+}
+
+/**
+ * Register `msg search` on the `msg` command.
+ *
+ * @param {import("commander").Command} msg - the `msg` command group
+ * @param {import("commander").Command} program - the root, for the global `--json`
+ */
+export function registerMsgSearch(msg, program) {
+    const cmd = msg
+        .command("search <query>")
+        .description(
+            "Search the local message cache (no login, no network). Accent-insensitive by default: 'duoc' finds 'được'.",
+        )
+        .option("-t, --thread <id>", "Only this conversation")
+        .option("--from <sender>", "Only messages from this sender (a user id, or 'me')")
+        .option("--since <date>", "Only on or after this date (YYYY-MM-DD, local time)")
+        .option("--until <date>", "Only on or before this date (YYYY-MM-DD, local time)")
+        .option("--last <period>", "Only the last 7d, 2w, 3m, 1y (instead of --since)")
+        .option("--type <types>", "Only these message types: text, photo, video, file, link, sticker... (comma list)")
+        .option("-n, --limit <n>", "Hits per page (default: every hit, no paging)", parseIntAtLeast(1))
+        .option("--cursor <cursor>", "Next page: the cursor printed under the previous one")
+        .option(
+            "--context <n>",
+            `Show n messages before and after each hit (at most ${MAX_CONTEXT})`,
+            parseIntAtLeast(0),
+            0,
+        )
+        .option("--exact", "Accents must match too (case still does not)")
+        .action((query, opts) => {
+            const jsonMode = program.opts().json;
+            const account = getActive();
+            if (!account) {
+                error("No active account. Please login first.");
+                process.exit(1);
+            }
+            let page;
+            let names;
+            try {
+                initDb(getAccountDbPath(account.ownId));
+                configureSearchIndex({ onProgress: indexProgressReporter((line) => info(line)) });
+                page = searchPage({
+                    query,
+                    accents: opts.exact ? "exact" : "fold",
+                    types: opts.type,
+                    limit: opts.limit,
+                    cursor: opts.cursor,
+                    context: opts.context,
+                    ...filtersFromOptions(opts, account.ownId),
+                    // Hidden chats are left out, as Zalo's search leaves them out. This command has no session,
+                    // so the ids come from the mirror the listener and the hidden-chat commands keep.
+                    excludeThreadIds: [
+                        ...hiddenChatsFor(account.ownId, { stateDir: getAccountDir(account.ownId) }).ids,
+                    ],
+                });
+                names = getThreadNames();
+            } catch (e) {
+                error(e.message);
+                process.exit(1);
+            }
+            const hits = page.hits.map((h) => hitToJson(h, names));
+            output(
+                {
+                    query: page.query,
+                    accents: page.accents,
+                    truncatedKeyword: page.truncatedKeyword,
+                    count: page.count,
+                    hasMore: page.hasMore,
+                    nextCursor: page.nextCursor,
+                    counts: page.counts,
+                    coverage: page.coverage,
+                    hits,
+                },
+                jsonMode,
+                () => {
+                    const mode = page.accents === "exact" ? "accents must match" : "accents ignored";
+                    info(`${page.count} result(s) for "${page.query}" (${mode})${page.hasMore ? ", more below" : ""}`);
+                    if (page.truncatedKeyword) info("The keyword was cut to 100 characters.");
+                    for (const h of hits) printHit(h);
+                    if (page.counts && Object.keys(page.counts).length) {
+                        const tabs = Object.entries(page.counts)
+                            .sort((a, b) => b[1] - a[1])
+                            .map(([t, n]) => `${t || "other"} ${n}`)
+                            .join(" · ");
+                        info(`Matches by type: ${tabs}`);
+                    }
+                    if (page.hasMore) info(`More: add --cursor ${page.nextCursor}`);
+                    info(page.coverage.note);
+                },
+            );
+        });
+    // The preAction hook logs in before most commands. This one reads the cache and nothing else.
+    cmd.zaloLocalOnly = true;
+    return cmd;
+}