cli-whatsapp 0.1.1 → 0.1.3

package/dist/cli/commands/sync.js

@@ -0,0 +1,67 @@
+import { connect, runWithConnection } from "../../whatsapp/client.js";
+import { registerPersistence, extractText, isGroupJid } from "../../whatsapp/events.js";
+import { countMessages, listChats, findChat } from "../../db/sqlite.js";
+import { loadConfig, saveConfig } from "../../config/index.js";
+import { ok, info, print } from "../../utils/ui.js";
+import { c, formatTime, displayName } from "../../utils/format.js";
+import { notify } from "../../utils/notify.js";
+/** wa sync [--seconds N] — pull recent chats/messages into the local cache. */
+export async function sync(opts) {
+    const seconds = Math.min(Math.max(parseInt(opts.seconds ?? '12', 10) || 12, 3), 120);
+    const before = { chats: listChats(5000).length, msgs: countMessages() };
+    info(`Syncing for ~${seconds}s… (WhatsApp streams history in the background)`);
+    await runWithConnection(async (conn) => {
+        registerPersistence(conn.sock);
+        // Periodic progress so long syncs don't look frozen.
+        const started = Date.now();
+        const timer = setInterval(() => {
+            const elapsed = Math.round((Date.now() - started) / 1000);
+            process.stdout.write(`\r${c.dim(`  ${elapsed}s — ${countMessages()} messages cached`)}   `);
+        }, 1000);
+        await new Promise((r) => setTimeout(r, seconds * 1000));
+        clearInterval(timer);
+        process.stdout.write('\r' + ' '.repeat(50) + '\r');
+    }, { requireSession: true, syncFullHistory: true });
+    const after = { chats: listChats(5000).length, msgs: countMessages() };
+    const cfg = loadConfig();
+    cfg.session.lastSyncAt = Date.now();
+    saveConfig(cfg);
+    ok(`Sync complete. +${after.chats - before.chats} chats, +${after.msgs - before.msgs} messages ` +
+        `(${after.chats} chats, ${after.msgs} messages total).`);
+}
+/** wa watch — stream incoming messages live until interrupted. */
+export async function watch() {
+    const cfg = loadConfig();
+    info('Watching for incoming messages. Press Ctrl+C to stop.');
+    print(c.dim('─'.repeat(40)));
+    const conn = await connect({ requireSession: true });
+    registerPersistence(conn.sock, {
+        onMessage: (msg) => {
+            if (msg.key.fromMe)
+                return;
+            const jid = msg.key.remoteJid;
+            if (!jid || jid === 'status@broadcast')
+                return;
+            const text = extractText(msg.message) || c.dim('[media]');
+            const chat = findChat(jid);
+            const name = chat ? displayName(chat) : (msg.pushName ?? jid.split('@')[0]);
+            const sender = isGroupJid(jid) && msg.pushName ? `${name}/${msg.pushName}` : name;
+            const time = c.gray(formatTime(Date.now(), cfg.preferences.time24h));
+            print(`${time} ${c.cyan(sender)}: ${text}`);
+            if (cfg.preferences.notifications)
+                notify(sender, extractText(msg.message) || 'sent media');
+        },
+    });
+    await conn.ready;
+    ok('Connected. Live.');
+    // Keep the process alive until the user interrupts.
+    await new Promise((resolve) => {
+        const stop = () => {
+            conn.close();
+            print('\n' + c.dim('Stopped watching.'));
+            resolve();
+        };
+        process.on('SIGINT', stop);
+        process.on('SIGTERM', stop);
+    });
+}

package/dist/cli/index.js

@@ -0,0 +1,174 @@
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { login, logout, status } from "./commands/auth.js";
+import { chats, contacts, open, history, search } from "./commands/read.js";
+import { send, reply } from "./commands/send.js";
+import { sync, watch } from "./commands/sync.js";
+import { exportChat } from "./commands/export.js";
+import { config, doctor, version } from "./commands/misc.js";
+import { shell } from "./commands/shell.js";
+import { media, download } from "./commands/media.js";
+import { recent, pin, unpin, archive, unarchive } from "./commands/manage.js";
+import { group } from "./commands/group.js";
+import { closeDb } from "../db/sqlite.js";
+import { whenWritesSettled } from "../whatsapp/client.js";
+import { installConsoleFilter } from "../whatsapp/logger.js";
+import { printError } from "../utils/ui.js";
+import { c } from "../utils/format.js";
+// Suppress libsignal's direct console noise (unless WA_DEBUG).
+installConsoleFilter();
+function pkgVersion() {
+    try {
+        const p = join(new URL('../../', import.meta.url).pathname, 'package.json');
+        return JSON.parse(readFileSync(p, 'utf8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/**
+ * Wrap an async command so failures print cleanly and the process always exits.
+ * We exit explicitly because commands that opened a WhatsApp socket leave
+ * background handles (keep-alive timers, the websocket, history-sync work) that
+ * would otherwise keep Node alive and hang the terminal after the work is done.
+ */
+function run(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+            // Let any in-flight credential writes finish before exiting, or we risk
+            // truncating a session file mid-write and corrupting the login.
+            await whenWritesSettled();
+            closeDb();
+            process.exit(0);
+        }
+        catch (err) {
+            printError(err);
+            await whenWritesSettled();
+            closeDb();
+            process.exit(1);
+        }
+    };
+}
+const program = new Command();
+program
+    .name('wa')
+    .description('A fast, terminal-first WhatsApp client.')
+    .version(pkgVersion(), '-v, --version', 'output the version number')
+    .configureHelp({ sortSubcommands: true })
+    .addHelpText('after', `\nExamples:\n` +
+    `  ${c.dim('$')} wa login              ${c.dim('# link this device via QR')}\n` +
+    `  ${c.dim('$')} wa sync               ${c.dim('# pull recent chats & messages')}\n` +
+    `  ${c.dim('$')} wa chats              ${c.dim('# list conversations')}\n` +
+    `  ${c.dim('$')} wa open Alice         ${c.dim('# read a conversation')}\n` +
+    `  ${c.dim('$')} wa send Alice "Hi!"   ${c.dim('# send a message')}\n` +
+    `  ${c.dim('$')} wa search invoice     ${c.dim('# search cached messages')}\n`);
+// ---- Authentication --------------------------------------------------------
+program
+    .command('login [mode]')
+    .description('Link this device — pairing code by default; `wa login qr` to use a QR')
+    .option('-p, --phone <number>', 'number for the pairing code (skips the prompt)')
+    .action(run(login));
+program.command('logout').description('Unlink this device and wipe local session').action(run(logout));
+program.command('status').description('Show login and cache status').action(run(status));
+// ---- Reading (offline, from local cache) -----------------------------------
+program
+    .command('chats')
+    .description('List conversations (most recent first)')
+    .option('-a, --all', 'include archived chats')
+    .option('-n, --limit <n>', 'max chats to show')
+    .action(run(chats));
+program
+    .command('contacts')
+    .description('List known contacts')
+    .option('-n, --limit <n>', 'max contacts to show')
+    .action(run(contacts));
+program
+    .command('open <chat>')
+    .description('Show the latest messages in a chat')
+    .option('-n, --limit <n>', 'number of messages')
+    .action(run(open));
+program
+    .command('history <chat>')
+    .description('Show extended message history for a chat')
+    .option('-n, --limit <n>', 'number of messages (default 200)')
+    .action(run(history));
+program
+    .command('search <text>')
+    .description('Search cached messages')
+    .option('-n, --limit <n>', 'max results')
+    .action(run(search));
+// ---- Writing (requires connection) -----------------------------------------
+program
+    .command('send <chat> [message]')
+    .description('Send a message, or media with --file (message becomes the caption)')
+    .option('-f, --file <path>', 'attach an image/video/audio/document to send')
+    .action(run(send));
+program
+    .command('reply <id> <message>')
+    .description('Reply to a cached message by its #id')
+    .action(run(reply));
+// ---- Sync & live -----------------------------------------------------------
+program
+    .command('sync')
+    .description('Pull recent chats and messages into the local cache')
+    .option('-s, --seconds <n>', 'how long to sync (3-120)')
+    .action(run(sync));
+program.command('watch').description('Stream incoming messages live').action(run(watch));
+// ---- Media -----------------------------------------------------------------
+program
+    .command('media [type]')
+    .description('List cached media (photos, videos, audio, documents, stickers, all)')
+    .option('-n, --limit <n>', 'max items')
+    .action(run(media));
+program
+    .command('download <id>')
+    .description('Download & decrypt a cached media message by #id')
+    .option('-o, --out <file>', 'output file')
+    .action(run(download));
+// ---- Organize (local) ------------------------------------------------------
+program
+    .command('recent')
+    .description('Show most recently active chats')
+    .option('-n, --limit <n>', 'max chats')
+    .action(run(recent));
+program
+    .command('group [action] [args...]')
+    .description('Manage groups: info, invite, rename, add, remove, promote, demote, leave, create')
+    .action(run(group));
+program.command('pin <chat>').description('Pin a chat to the top (local)').action(run(pin));
+program.command('unpin <chat>').description('Unpin a chat (local)').action(run(unpin));
+program.command('archive <chat>').description('Archive a chat (local)').action(run(archive));
+program.command('unarchive <chat>').description('Unarchive a chat (local)').action(run(unarchive));
+// ---- Interactive -----------------------------------------------------------
+program
+    .command('shell', { isDefault: false })
+    .aliases(['chat', 'ui'])
+    .description('Start interactive mode (slash commands, live chat)')
+    .action(run(shell));
+// ---- Export ----------------------------------------------------------------
+program
+    .command('export <chat>')
+    .description('Export a conversation to markdown, text, or json')
+    .option('-f, --format <fmt>', 'md | txt | json', 'md')
+    .option('-n, --limit <n>', 'max messages', '1000')
+    .option('-o, --out <file>', 'output file ("-" for stdout)')
+    .action(run(exportChat));
+// ---- Utility ---------------------------------------------------------------
+program
+    .command('config [action] [key] [value]')
+    .description('View or edit config (e.g. `wa config set time24h false`)')
+    .action(run(config));
+program.command('doctor').description('Run self-diagnostics').action(run(doctor));
+program.command('version').description('Print the version').action(run(version));
+// Bare `wa` (no subcommand) drops into interactive mode.
+if (process.argv.slice(2).length === 0) {
+    await run(shell)();
+}
+else {
+    await program.parseAsync(process.argv).catch((err) => {
+        printError(err);
+        process.exit(1);
+    });
+}

package/dist/config/index.js

@@ -0,0 +1,59 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+/**
+ * All persistent state lives under a single base directory so it's easy to back
+ * up or wipe. Defaults to ~/.cli-whatsapp in the user's home — a stable location
+ * that survives package updates (never inside node_modules). Override with
+ * WA_HOME (e.g. for tests or a portable install).
+ */
+export const BASE_DIR = resolve(process.env.WA_HOME ?? join(homedir(), '.cli-whatsapp'));
+export const PATHS = {
+    base: BASE_DIR,
+    sessions: join(BASE_DIR, 'sessions'),
+    data: join(BASE_DIR, 'data'),
+    media: join(BASE_DIR, 'media'),
+    db: join(BASE_DIR, 'data', 'whatsapp.db'),
+    config: join(BASE_DIR, 'config.json'),
+};
+const DEFAULT_CONFIG = {
+    preferences: { openLimit: 30, time24h: true, notifications: true, autoConnect: true },
+    ai: { enabled: false },
+    session: {},
+};
+/** Ensure every runtime directory exists (idempotent, cheap). */
+export function ensureDirs() {
+    for (const dir of [PATHS.sessions, PATHS.data, PATHS.media]) {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+    }
+}
+export function loadConfig() {
+    if (!existsSync(PATHS.config))
+        return structuredClone(DEFAULT_CONFIG);
+    try {
+        const raw = JSON.parse(readFileSync(PATHS.config, 'utf8'));
+        // Shallow-merge so new default keys appear for old config files.
+        return {
+            ...DEFAULT_CONFIG,
+            ...raw,
+            preferences: { ...DEFAULT_CONFIG.preferences, ...raw.preferences },
+            ai: { ...DEFAULT_CONFIG.ai, ...raw.ai },
+            session: { ...DEFAULT_CONFIG.session, ...raw.session },
+        };
+    }
+    catch {
+        // Corrupt config should never crash the CLI; fall back to defaults.
+        return structuredClone(DEFAULT_CONFIG);
+    }
+}
+export function saveConfig(config) {
+    ensureDirs();
+    writeFileSync(PATHS.config, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+/** Convenience: patch a subset of config and persist. */
+export function updateConfig(patch) {
+    const next = { ...loadConfig(), ...patch };
+    saveConfig(next);
+    return next;
+}

package/{src/db/schema.ts → dist/db/schema.js}

@@ -5,7 +5,6 @@
  * `schema_version` in the `settings` table lets us evolve this safely later.
  */
 export const SCHEMA_VERSION = 2;
-
 export const SCHEMA_SQL = /* sql */ `
 PRAGMA journal_mode = WAL;      -- concurrent read while writing (watch + reads)
 PRAGMA synchronous = NORMAL;    -- fast, safe enough for a local cache

package/dist/db/sqlite.js

@@ -0,0 +1,237 @@
+import { DatabaseSync } from 'node:sqlite';
+import { ensureDirs, PATHS } from "../config/index.js";
+import { SCHEMA_SQL, SCHEMA_VERSION } from "./schema.js";
+let db = null;
+/** Open (or reuse) the singleton database connection and apply the schema. */
+export function getDb() {
+    if (db)
+        return db;
+    ensureDirs();
+    db = new DatabaseSync(PATHS.db);
+    db.exec(SCHEMA_SQL);
+    migrate(db);
+    setSetting('schema_version', String(SCHEMA_VERSION));
+    return db;
+}
+/** Additive, idempotent migrations for databases created by older versions. */
+function migrate(dbc) {
+    ensureColumn(dbc, 'messages', 'raw', 'TEXT');
+}
+function ensureColumn(dbc, table, column, type) {
+    const cols = dbc.prepare(`PRAGMA table_info(${table})`).all();
+    if (!cols.some((c) => c.name === column)) {
+        dbc.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+    }
+}
+export function closeDb() {
+    if (db) {
+        db.close();
+        db = null;
+    }
+}
+// ---- settings key/value helpers -------------------------------------------
+export function getSetting(key) {
+    const row = getDb()
+        .prepare('SELECT value FROM settings WHERE key = ?')
+        .get(key);
+    return row?.value ?? null;
+}
+export function setSetting(key, value) {
+    getDb()
+        .prepare(`INSERT INTO settings (key, value) VALUES (?, ?)
+       ON CONFLICT(key) DO UPDATE SET value = excluded.value`)
+        .run(key, value);
+}
+// ---- upserts ---------------------------------------------------------------
+export function upsertContact(c) {
+    getDb()
+        .prepare(`INSERT INTO contacts (jid, name, phone, updatedAt)
+       VALUES (@jid, @name, @phone, @updatedAt)
+       ON CONFLICT(jid) DO UPDATE SET
+         name  = COALESCE(excluded.name, contacts.name),
+         phone = COALESCE(excluded.phone, contacts.phone),
+         updatedAt = excluded.updatedAt`)
+        .run({
+        jid: c.jid,
+        name: c.name ?? null,
+        phone: c.phone ?? null,
+        updatedAt: Date.now(),
+    });
+}
+export function upsertChat(c) {
+    getDb()
+        .prepare(`INSERT INTO chats (jid, name, lastMessage, lastTimestamp, unreadCount, archived, pinned, isGroup)
+       VALUES (@jid, @name, @lastMessage, @lastTimestamp, @unreadCount, @archived, @pinned, @isGroup)
+       ON CONFLICT(jid) DO UPDATE SET
+         name          = COALESCE(excluded.name, chats.name),
+         lastMessage   = COALESCE(excluded.lastMessage, chats.lastMessage),
+         lastTimestamp = MAX(excluded.lastTimestamp, chats.lastTimestamp),
+         unreadCount   = excluded.unreadCount,
+         archived      = excluded.archived,
+         pinned        = excluded.pinned,
+         isGroup       = excluded.isGroup`)
+        .run({
+        jid: c.jid,
+        name: c.name ?? null,
+        lastMessage: c.lastMessage ?? null,
+        lastTimestamp: c.lastTimestamp ?? 0,
+        unreadCount: c.unreadCount ?? 0,
+        archived: c.archived ?? 0,
+        pinned: c.pinned ?? 0,
+        isGroup: c.isGroup ?? 0,
+    });
+}
+export function insertMessage(m) {
+    getDb()
+        .prepare(`INSERT INTO messages (chatJid, messageId, sender, text, timestamp, status, type, fromMe, mediaPath, raw)
+       VALUES (@chatJid, @messageId, @sender, @text, @timestamp, @status, @type, @fromMe, @mediaPath, @raw)
+       ON CONFLICT(chatJid, messageId) DO UPDATE SET
+         text      = COALESCE(excluded.text, messages.text),
+         status    = COALESCE(excluded.status, messages.status),
+         mediaPath = COALESCE(excluded.mediaPath, messages.mediaPath),
+         raw       = COALESCE(excluded.raw, messages.raw)`)
+        .run({
+        chatJid: m.chatJid,
+        messageId: m.messageId,
+        sender: m.sender ?? null,
+        text: m.text ?? null,
+        timestamp: m.timestamp,
+        status: m.status ?? null,
+        type: m.type ?? null,
+        fromMe: m.fromMe ? 1 : 0,
+        mediaPath: m.mediaPath ?? null,
+        raw: m.raw ?? null,
+    });
+}
+/** Update the local media file path once a media message is downloaded. */
+export function setMediaPath(id, path) {
+    getDb().prepare('UPDATE messages SET mediaPath = ? WHERE id = ?').run(path, id);
+}
+// ---- queries ---------------------------------------------------------------
+// Chat rows with the display name resolved: prefer the chat's own name, then
+// fall back to a known contact name for the same jid (direct chats often have
+// no name of their own). Column order/shape matches ChatRow.
+const CHAT_SELECT = `
+  SELECT c.jid,
+         COALESCE(c.name, ct.name) AS name,
+         c.lastMessage, c.lastTimestamp, c.unreadCount,
+         c.archived, c.pinned, c.isGroup
+  FROM chats c
+  LEFT JOIN contacts ct ON ct.jid = c.jid`;
+export function listChats(limit = 50, includeArchived = false) {
+    return getDb()
+        .prepare(`${CHAT_SELECT}
+       ${includeArchived ? '' : 'WHERE c.archived = 0'}
+       ORDER BY c.pinned DESC, c.lastTimestamp DESC
+       LIMIT ?`)
+        .all(limit);
+}
+export function listContacts(limit = 500) {
+    return getDb()
+        .prepare(`SELECT * FROM contacts WHERE name IS NOT NULL ORDER BY name COLLATE NOCASE LIMIT ?`)
+        .all(limit);
+}
+export function getMessages(chatJid, limit = 30) {
+    // Newest N, returned oldest-first for natural chat reading order.
+    const rows = getDb()
+        .prepare(`SELECT * FROM messages WHERE chatJid = ?
+       ORDER BY timestamp DESC, id DESC LIMIT ?`)
+        .all(chatJid, limit);
+    return rows.reverse();
+}
+export function searchMessages(term, limit = 50) {
+    return getDb()
+        .prepare(`SELECT * FROM messages WHERE text LIKE ? ESCAPE '\\'
+       ORDER BY timestamp DESC LIMIT ?`)
+        .all(`%${escapeLike(term)}%`, limit);
+}
+function escapeLike(s) {
+    return s.replace(/[\\%_]/g, (m) => '\\' + m);
+}
+/**
+ * Build a forgiving LIKE pattern: escape wildcards, then let any run of
+ * whitespace in the query match any characters. So "Vishwas @Mobius" matches a
+ * stored "Vishwas  @Mobius" (double space) or "Vishwas · @Mobius".
+ */
+function likePattern(query) {
+    return `%${escapeLike(query).replace(/\s+/g, '%')}%`;
+}
+/** Resolve a user-typed chat identifier (name fragment or jid) to a chat. */
+export function findChat(query) {
+    const dbc = getDb();
+    // Exact jid first.
+    const exact = dbc
+        .prepare(`${CHAT_SELECT} WHERE c.jid = ?`)
+        .get(query);
+    if (exact)
+        return exact;
+    // Bare phone number → match the number portion of a direct-chat jid.
+    const digits = query.replace(/[^\d]/g, '');
+    if (digits.length >= 5 && digits === query.replace(/[+\s()\-]/g, '')) {
+        const byNum = dbc
+            .prepare(`${CHAT_SELECT} WHERE c.jid LIKE ? ORDER BY c.lastTimestamp DESC LIMIT 1`)
+            .get(`${digits}@%`);
+        if (byNum)
+            return byNum;
+    }
+    // Case-insensitive name match (chat's own name OR the linked contact name),
+    // preferring the most recently active.
+    const byName = dbc
+        .prepare(`${CHAT_SELECT}
+       WHERE COALESCE(c.name, ct.name) LIKE ? ESCAPE '\\'
+       ORDER BY (COALESCE(c.name, ct.name) = ? COLLATE NOCASE) DESC,
+                c.lastTimestamp DESC
+       LIMIT 1`)
+        .get(likePattern(query), query);
+    return byName ?? null;
+}
+/** Media messages, optionally filtered by type (image/video/audio/document/sticker). */
+export function listMedia(types, limit = 50) {
+    const dbc = getDb();
+    if (types && types.length) {
+        const placeholders = types.map(() => '?').join(',');
+        return dbc
+            .prepare(`SELECT * FROM messages WHERE type IN (${placeholders})
+         ORDER BY timestamp DESC LIMIT ?`)
+            .all(...types, limit);
+    }
+    return dbc
+        .prepare(`SELECT * FROM messages
+       WHERE type IN ('image','video','audio','document','sticker')
+       ORDER BY timestamp DESC LIMIT ?`)
+        .all(limit);
+}
+/** Recent chats by activity, ignoring pin priority. */
+export function recentChats(limit = 15) {
+    return getDb()
+        .prepare(`${CHAT_SELECT} WHERE c.archived = 0 ORDER BY c.lastTimestamp DESC LIMIT ?`)
+        .all(limit);
+}
+export function setPinned(jid, pinned) {
+    getDb().prepare('UPDATE chats SET pinned = ? WHERE jid = ?').run(pinned ? 1 : 0, jid);
+}
+export function setArchived(jid, archived) {
+    getDb().prepare('UPDATE chats SET archived = ? WHERE jid = ?').run(archived ? 1 : 0, jid);
+}
+/** Resolve a contact by name fragment (used to start a chat with no history). */
+export function findContact(query) {
+    const row = getDb()
+        .prepare(`SELECT * FROM contacts
+       WHERE name IS NOT NULL AND name LIKE ? ESCAPE '\\'
+       ORDER BY (name = ? COLLATE NOCASE) DESC, LENGTH(name) ASC
+       LIMIT 1`)
+        .get(likePattern(query), query);
+    return row ?? null;
+}
+export function getMessageById(id) {
+    const row = getDb()
+        .prepare('SELECT * FROM messages WHERE id = ?')
+        .get(id);
+    return row ?? null;
+}
+export function countMessages() {
+    const row = getDb()
+        .prepare('SELECT COUNT(*) AS n FROM messages')
+        .get();
+    return row.n;
+}

package/dist/utils/format.js

@@ -0,0 +1,89 @@
+// Minimal ANSI styling — no dependency, respects NO_COLOR.
+const useColor = !process.env.NO_COLOR && process.stdout.isTTY;
+const wrap = (code) => (s) => useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s);
+// 24-bit truecolor for brand colors (modern terminals). Falls back to plain
+// text under NO_COLOR / non-TTY.
+const rgb = (r, g, b) => (s) => useColor ? `\x1b[38;2;${r};${g};${b}m${s}\x1b[0m` : String(s);
+// WhatsApp brand palette.
+export const BRAND = {
+    green: [37, 211, 102], // #25D366 signature green
+    teal: [18, 140, 126], // #128C7E
+    darkTeal: [7, 94, 84], // #075E54
+};
+export const c = {
+    bold: wrap('1'),
+    dim: wrap('2'),
+    green: rgb(...BRAND.green), // WhatsApp green (used for "me", ✓, accents)
+    teal: rgb(...BRAND.teal),
+    darkTeal: rgb(...BRAND.darkTeal),
+    cyan: wrap('36'),
+    yellow: wrap('33'),
+    magenta: wrap('35'),
+    red: wrap('31'),
+    gray: wrap('90'),
+};
+/** Human-friendly timestamp. Absolute time for today, date otherwise. */
+export function formatTime(ms, time24h = true) {
+    if (!ms)
+        return '';
+    const d = new Date(ms);
+    const now = new Date();
+    const sameDay = d.getFullYear() === now.getFullYear() &&
+        d.getMonth() === now.getMonth() &&
+        d.getDate() === now.getDate();
+    const time = d.toLocaleTimeString(undefined, {
+        hour: '2-digit',
+        minute: '2-digit',
+        hour12: !time24h,
+    });
+    if (sameDay)
+        return time;
+    const date = d.toLocaleDateString(undefined, {
+        month: 'short',
+        day: 'numeric',
+    });
+    return `${date} ${time}`;
+}
+export function displayName(chat) {
+    if (chat.name)
+        return chat.name;
+    // Fall back to the phone number portion of a direct jid.
+    const num = chat.jid.split('@')[0];
+    return chat.isGroup ? `Group ${num}` : `+${num}`;
+}
+/** Render the numbered chat list shown by `wa chats`. */
+export function renderChatList(chats, time24h = true) {
+    if (chats.length === 0) {
+        return c.dim('No chats yet. Run `wa sync` after logging in.');
+    }
+    const width = String(chats.length).length;
+    return chats
+        .map((chat, i) => {
+        const idx = c.dim(String(i + 1).padStart(width) + '.');
+        const name = c.bold(displayName(chat));
+        const pin = chat.pinned ? c.yellow(' 📌') : '';
+        const unread = chat.unreadCount > 0 ? c.green(` (${chat.unreadCount})`) : '';
+        const time = c.gray(formatTime(chat.lastTimestamp, time24h));
+        const preview = c.dim(truncate(chat.lastMessage ?? '', 48));
+        return `${idx} ${name}${pin}${unread}  ${time}\n     ${preview}`;
+    })
+        .join('\n');
+}
+/** Render a conversation transcript for `wa open` / `wa history`. */
+export function renderMessages(messages, time24h = true) {
+    if (messages.length === 0)
+        return c.dim('No messages.');
+    return messages
+        .map((m) => {
+        const time = c.gray(formatTime(m.timestamp, time24h));
+        const who = m.fromMe ? c.green('me') : c.cyan(m.sender ?? 'unknown');
+        const body = m.text ?? (m.type ? c.dim(`[${m.type}]`) : c.dim('[no text]'));
+        const id = c.dim(`#${m.id}`);
+        return `${time} ${who}: ${body} ${id}`;
+    })
+        .join('\n');
+}
+export function truncate(s, n) {
+    const oneLine = s.replace(/\s+/g, ' ').trim();
+    return oneLine.length > n ? oneLine.slice(0, n - 1) + '…' : oneLine;
+}

package/dist/utils/jid.js

@@ -0,0 +1,40 @@
+import { findChat, findContact } from "../db/sqlite.js";
+/** A raw phone number like +1 (415) 555-0000 → 14155550000@s.whatsapp.net */
+export function phoneToJid(input) {
+    const digits = input.replace(/[^\d]/g, '');
+    if (digits.length < 7)
+        return null;
+    return `${digits}@s.whatsapp.net`;
+}
+/**
+ * Resolve a user-supplied chat target to a jid.
+ * Order: exact jid → known chat (name/fuzzy) → raw phone number.
+ * Returns null when nothing plausible matches.
+ */
+export function resolveTarget(query) {
+    const q = query.trim();
+    if (!q)
+        return null;
+    // Already a full jid (ends with a WhatsApp domain, no spaces). Note: a
+    // contact name can contain "@" (e.g. "Vishwas @Mobius"), so we must match the
+    // domain suffix, not merely the presence of "@".
+    if (/^\S+@(s\.whatsapp\.net|g\.us|lid|c\.us|broadcast)$/.test(q)) {
+        return { jid: q, name: q, known: false };
+    }
+    const chat = findChat(q);
+    if (chat) {
+        return { jid: chat.jid, name: chat.name ?? chat.jid, known: true };
+    }
+    // Known contact with no existing chat yet (e.g. first message to someone).
+    const contact = findContact(q);
+    if (contact) {
+        return { jid: contact.jid, name: contact.name ?? contact.jid, known: true };
+    }
+    // Looks like a phone number.
+    if (/^[+\d][\d\s()\-]{5,}$/.test(q)) {
+        const jid = phoneToJid(q);
+        if (jid)
+            return { jid, name: q, known: false };
+    }
+    return null;
+}