@wirecat/cli-core 0.345.0 → 0.347.0

package/CHANGELOG.md

@@ -7,6 +7,47 @@ shape of this file.
 
 ## Unreleased
 
+## 0.347.0 — 18.10.2026
+
+### Added
+
+- **`loginQr` shows a login QR code the same way in every messenger CLI**: drawn on the diagnostic stream, which
+  `--quiet` does not hide, or written to the `--qr-file` PNG with `writeSecurely` (a temporary file created with
+  mode `0600`, renamed over the path, never chmodded afterwards). On a terminal too narrow for the code it draws
+  nothing and says to widen the terminal or pass `--qr-file`; it opens nothing. `close()` removes the image it
+  wrote, never a file it did not. `qrNeedsTerminal(command)` is the shared refusal when nobody could scan, and
+  `atTerminal(input)` the shared test. `parity.json` plans `--qr-file` on `session start` and `setup` for max, beside tg and wa.
+
+### Fixed
+
+- **A list that takes a query prints its help for `--help`.** Since 0.343.0, `chats list --help`, `tasks list --help`,
+  `contacts list --help` and every other list with `[query...]` refused `--help` as a mistyped option (exit 2), because
+  commander looks for it only after the query check had run. A mistyped `--limt` is still refused.
+- **`help` and `guide` need no permission key**: `keyForCommand` returned nothing for them, so a tool that maps every
+  command to a key (max) crashed on `help options`. They are housekeeping now, like `commands` and `skill`.
+- **`parity.json` has a `guide` row**, planned for max, tg and wa, so `cli-core-parity` stops failing a tool that
+  mounts it with "guide: not in the manifest".
+
+## 0.346.0 — 18.10.2026
+
+### Added
+
+- **The contract kit checks `listen`** when the adapter has it: on a signal already aborted it resolves at once
+  and does not reject, and otherwise it keeps listening until the signal aborts, then resolves. `OPTIONAL_METHODS`
+  lists `listen`, and `fakeAdapter(seed, { listen: true })` has it. The cases cannot see whether `listen` connects.
+
+### Changed — may break callers
+
+- **Saving a chat the store already holds merges its `providerMetadata` key by key, and `parentChatId` keeps or
+  clears the same way.** A metadata key the new chat leaves out keeps its stored value; a key set to `null` is
+  removed, and metadata with no key left is stored as none. `parentChatId` left out keeps the stored parent, `null`
+  clears it (it could never be cleared before), and `Chat.parentChatId` is now `Id | null`. Before, the new
+  metadata replaced the stored one whole, so a push that left a key out erased it: a WhatsApp community lost
+  `community: true` on a push that did not say, and max-cli's login erased each dialog's `partnerId`. **Adapters
+  must send `null` for a key that is gone, or a flag that turned false; an absent key now means unknown.** An
+  adapter that leaves such a key out keeps the old value in the store, and a stale `username` still answers to
+  `@name` until the chat is saved with `username: null`. Chats the store already holds are not changed.
+
 ## 0.345.0 — 18.10.2026
 
 ### Added

package/dist/cli/messenger/chat-answers.js

@@ -30,7 +30,7 @@ export const chatAnswer = (account, chat) => defined({
     muted: chat.muted,
     archived: chat.archived,
     membership_state: chat.membershipState,
-    parent_chat_id: chat.parentChatId,
+    parent_chat_id: chat.parentChatId ?? undefined,
     scope: chat.scope,
     provider_metadata: chat.providerMetadata,
     description: chat.description,

package/dist/domain/models.d.ts

@@ -19,7 +19,8 @@ export type ChatKind = "dialog" | "group" | "channel" | "saved" | "unknown";
 /** Where the owner stands in a chat. Kept apart from whether its messages are searchable: a chat left keeps them. */
 export type MembershipState = "joined" | "left" | "public" | "imported" | "archived" | "external";
 export interface Chat {
-    parentChatId?: Id;
+    /** Saving a chat: absent keeps the stored parent, `null` clears it. */
+    parentChatId?: Id | null;
     scope?: "personal" | "work";
     id: Id;
     title: string | null;
@@ -36,6 +37,10 @@ export interface Chat {
     unreadMentions?: number;
     /** Absent where the messenger does not say. */
     membershipState?: MembershipState;
+    /**
+     * Saving a chat merges this into the stored one key by key: a key left out keeps its stored value, a key set to
+     * `null` is removed. So a key that is gone, or a flag that turned false, is sent as `null`.
+     */
     providerMetadata?: ProviderMetadata;
 }
 /** A group's switches; `null` where the messenger does not say, or has no such switch. */

package/dist/index.d.ts

@@ -22,5 +22,6 @@ export { defaultRules, ModerationRules, moderationPathFor } from "./moderation/r
 export { type OutputOptions, resolveOutput } from "./output.js";
 export { pollLines, type RenderOptions, renderMessage, renderMessages } from "./render/messages.js";
 export { isId, type PeopleLookup, pickChat, pickPerson } from "./resolve.js";
+export { atTerminal, type LoginQr, type LoginQrOptions, loginQr, qrNeedsTerminal, } from "./terminal/login-qr.js";
 export { readSecret, type SecretInput } from "./terminal/prompt.js";
 export { qrPng, terminalQr } from "./terminal/qr.js";

package/dist/index.js

@@ -15,5 +15,6 @@ export { defaultRules, ModerationRules, moderationPathFor } from "./moderation/r
 export { resolveOutput } from "./output.js";
 export { pollLines, renderMessage, renderMessages } from "./render/messages.js";
 export { isId, pickChat, pickPerson } from "./resolve.js";
+export { atTerminal, loginQr, qrNeedsTerminal, } from "./terminal/login-qr.js";
 export { readSecret } from "./terminal/prompt.js";
 export { qrPng, terminalQr } from "./terminal/qr.js";

package/dist/kit/contract.d.ts

@@ -16,13 +16,13 @@ export interface ContractOptions {
     ids?: IdMaker;
     /** As the messenger's `fetching.orderBy`: whether `history`'s `before` is a message id or an ISO time. */
     orderBy?: "id" | "time";
-    /** How long `watch` may take to say it listens, and to end once aborted. */
+    /** How long `watch` may take to say it listens, and `watch`, `listen` and `feed` to end once aborted. */
     waitMs?: number;
     /** As the messenger's `history`: a `"server"` messenger's adapter must have every `ServerReads` method. */
     history?: "server" | "store";
 }
 /** Every method of the optional groups, which `capability` hands over or refuses. */
-export declare const OPTIONAL_METHODS: readonly ["fetchCounters", "chats", "history", "around", "contact", "historyAfter", "historyBefore", "topics", "inspect", "edit", "forward", "delete", "pin", "unpin", "star", "react", "markRead", "markTopicRead", "poll", "vote", "closePoll", "createPoll", "watch", "feed", "download", "transcribe", "scheduled", "members", "admins", "chatEvents", "sessions", "lookup", "addressBook", "people", "createGroup", "join", "leave", "group", "updateGroup", "resetInviteLink", "addMembers", "removeMembers", "addAdmin", "removeAdmin", "folders", "createFolder", "updateFolder", "deleteFolder", "addContact", "removeContact", "block", "unblock", "renameContact", "importContacts", "updateProfile", "endOtherSessions"];
+export declare const OPTIONAL_METHODS: readonly ["fetchCounters", "chats", "history", "around", "contact", "historyAfter", "historyBefore", "topics", "inspect", "edit", "forward", "delete", "pin", "unpin", "star", "react", "markRead", "markTopicRead", "poll", "vote", "closePoll", "createPoll", "watch", "listen", "feed", "download", "transcribe", "scheduled", "members", "admins", "chatEvents", "sessions", "lookup", "addressBook", "people", "createGroup", "join", "leave", "group", "updateGroup", "resetInviteLink", "addMembers", "removeMembers", "addAdmin", "removeAdmin", "folders", "createFolder", "updateFolder", "deleteFolder", "addContact", "removeContact", "block", "unblock", "renameContact", "importContacts", "updateProfile", "endOtherSessions"];
 /**
  * The port's promises as cases any test runner can run: each connects through `connect`, checks
  * with `node:assert/strict` and closes the adapter. None needs a live service.

package/dist/kit/contract.js

@@ -28,6 +28,7 @@ export const OPTIONAL_METHODS = [
     "closePoll",
     "createPoll",
     "watch",
+    "listen",
     "feed",
     "download",
     "transcribe",
@@ -82,6 +83,17 @@ const within = async (work, failure, ms) => {
         clearTimeout(timer);
     }
 };
+const settledSoon = async (work) => {
+    let settled = false;
+    work.then(() => {
+        settled = true;
+    }, () => {
+        settled = true;
+    });
+    for (let turn = 0; turn < 5; turn += 1)
+        await new Promise((resolve) => setImmediate(resolve));
+    return settled;
+};
 const idsOf = (messages) => messages.map((message) => message.id);
 /** Every `id`, `chatId` and `senderId` anywhere in `value`, so a number among them is caught. */
 const everyId = (value, found = []) => {
@@ -394,6 +406,30 @@ export const contractCases = ({ connect, ids = wordIds, orderBy = "id", waitMs =
                 },
                 "`connect` opens a connection that listens, as `{ listen: true }` does",
             ],
+            [
+                "listen on a signal already aborted resolves at once and does not reject",
+                async (adapter) => {
+                    const skipped = lacking(adapter, "listen");
+                    if (skipped)
+                        return skipped;
+                    const controller = new AbortController();
+                    controller.abort();
+                    await within(Promise.resolve(adapter.listen?.(() => { }, controller.signal)), "listen did not resolve on a signal already aborted", waitMs);
+                },
+            ],
+            [
+                "listen keeps listening until the signal aborts, then resolves",
+                async (adapter) => {
+                    const skipped = lacking(adapter, "listen");
+                    if (skipped)
+                        return skipped;
+                    const controller = new AbortController();
+                    const listening = Promise.resolve(adapter.listen?.(() => { }, controller.signal));
+                    assert.equal(await settledSoon(listening), false, "listen ended before the signal aborted");
+                    controller.abort();
+                    await within(listening, "listen did not end when the signal aborted", waitMs);
+                },
+            ],
             [
                 "feed pushes only the seed's chats and messages, with ids as strings, and ends when the signal aborts",
                 async (adapter, seed) => {

package/dist/kit/fake.d.ts

@@ -1,7 +1,8 @@
-import type { AccountEditing, AccountTools, ChatFolders, ChatReading, ContactBook, GroupAdmin, GroupModeration, LiveUpdates, MessageEditing, MessageMedia, MessagePins, MessagePolls, MessageReactions, MessageStars, MessengerCore, PushedHistory, ReadState, ScheduledMessages, ServerReads, TopicReadState } from "../ports/messenger.js";
+import type { AccountEditing, AccountTools, ChatFolders, ChatReading, ContactBook, GroupAdmin, GroupModeration, LiveUpdates, MessageEditing, MessageMedia, MessagePins, MessagePolls, MessageReactions, MessageStars, MessengerCore, PassiveUpdates, PushedHistory, ReadState, ScheduledMessages, ServerReads, TopicReadState } from "../ports/messenger.js";
 import { type Seed } from "./seed.js";
 /** Every group of the port, over memory. */
-export type FakeAdapter = MessengerCore & ServerReads & ChatReading & MessageEditing & MessagePins & MessageStars & MessageReactions & ReadState & TopicReadState & MessagePolls & LiveUpdates & MessageMedia & ScheduledMessages & GroupModeration & AccountTools & GroupAdmin & ChatFolders & ContactBook & AccountEditing & Partial<PushedHistory>;
+export type FakeAdapter = MessengerCore & ServerReads & ChatReading & MessageEditing & MessagePins & MessageStars & MessageReactions & ReadState & TopicReadState & MessagePolls & LiveUpdates & MessageMedia & ScheduledMessages & GroupModeration & AccountTools & GroupAdmin & ChatFolders & ContactBook & AccountEditing & Partial<PushedHistory> & Partial<PassiveUpdates>;
 export declare const fakeAdapter: (seed?: Seed, options?: {
     feed?: boolean;
+    listen?: boolean;
 }) => FakeAdapter;

package/dist/kit/fake.js

@@ -28,6 +28,7 @@ const missing = (what) => new CliError("not_found", `the fake adapter has no ${w
  *
  * With `{ feed: true }` it also pushes its history, as a messenger with `history: "store"` does:
  * the chats and people in one batch, then each chat's messages in a batch of their own.
+ * With `{ listen: true }` it also has `listen`, which hands on what `watch` does.
  */
 const withRules = (folder, { emoji, include, skip, exclude, pin }) => {
     if (emoji !== undefined)
@@ -311,6 +312,17 @@ export const fakeAdapter = (seed = contractSeed(), options = {}) => {
             await new Promise((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
             listeners.delete(onEvent);
         },
+        ...(options.listen
+            ? {
+                listen: async (onEvent, signal) => {
+                    if (signal.aborted)
+                        return;
+                    listeners.add(onEvent);
+                    await new Promise((resolve) => signal.addEventListener("abort", () => resolve(), { once: true }));
+                    listeners.delete(onEvent);
+                },
+            }
+            : {}),
         ...(options.feed
             ? {
                 feed: async (onBatch, signal) => {

package/dist/meetings/cli/query-options.js

@@ -8,7 +8,11 @@ export const queryWordsAfterOptions = (command) => {
     command.parseOptions = (args) => {
         const parsed = parse(args);
         const end = parsed.unknown.indexOf("--");
-        const typo = parsed.unknown.slice(0, end < 0 ? undefined : end).find((word) => word.startsWith("--"));
+        // Commander looks for --help in what parseOptions leaves unknown, after it returns.
+        const help = command._getHelpOption();
+        const typo = parsed.unknown
+            .slice(0, end < 0 ? undefined : end)
+            .find((word) => word.startsWith("--") && !help?.is(word));
         if (typo !== undefined) {
             command.allowUnknownOption(false);
             command.unknownOption(typo);

package/dist/sends/permissions.js

@@ -341,6 +341,8 @@ export const WRITE_KEYS = [
 ];
 /** Commands that look after the tool and its files and never show a message: no level stops them. */
 const HOUSEKEEPING = new Set([
+    "help",
+    "guide",
     "config",
     "session",
     "doctor",

package/dist/store/sqlite/chats.js

@@ -4,7 +4,7 @@ import { identityPk } from "./identities.js";
 import { bound } from "./query-filter.js";
 import { chatEventPeople, chatEvents, chatMembers, chats, chunks, fetchLeases, identities, involvements, memberCounts, memberObservationMembers, memberObservations, memberStays, messageRevisions, messages, messageTranscripts, pollVotes, syncRanges, } from "./schema.js";
 import { ensureTag } from "./tags.js";
-import { json, parsed, present, toIso, toMs } from "./values.js";
+import { parsed, present, toIso, toMs } from "./values.js";
 /** The chat's own id, when the store key is a chat of this account. */
 export const chatOf = ({ orm }, accountKey, chatKey) => orm
     .select({ id: chats.externalId })
@@ -31,7 +31,12 @@ export const chatPkFor = (context, accountKey, chatId) => findChatPk(context, ac
         .get()?.pk);
 export const upsertChat = (context, accountKey, chat) => {
     const { orm, now } = context;
-    const parent = chat.parentChatId === undefined ? null : chatPkFor(context, accountKey, chat.parentChatId);
+    const parent = chat.parentChatId == null ? null : chatPkFor(context, accountKey, chat.parentChatId);
+    const stored = orm
+        .select({ metadata: chats.metadata })
+        .from(chats)
+        .where(and(eq(chats.accountId, accountKey), eq(chats.externalId, chat.id)))
+        .get();
     orm
         .insert(chats)
         .values({
@@ -44,7 +49,7 @@ export const upsertChat = (context, accountKey, chat) => {
         unreadCount: chat.unreadCount,
         lastMessageAt: toMs(chat.lastMessageAt),
         participantsCount: chat.participantsCount,
-        metadata: json(chat.providerMetadata),
+        metadata: mergedMetadata(stored?.metadata ?? null, chat.providerMetadata),
         membershipState: chat.membershipState ?? null,
         createdAt: now(),
         updatedAt: now(),
@@ -53,7 +58,7 @@ export const upsertChat = (context, accountKey, chat) => {
         target: [chats.accountId, chats.externalId],
         set: {
             kind: sql `excluded.kind`,
-            parentChatId: sql `coalesce(excluded.parent_chat_id, ${chats.parentChatId})`,
+            ...(chat.parentChatId === undefined ? {} : { parentChatId: sql `excluded.parent_chat_id` }),
             scope: sql `coalesce(excluded.scope, ${chats.scope})`,
             title: sql `excluded.title`,
             unreadCount: sql `excluded.unread_count`,
@@ -68,6 +73,22 @@ export const upsertChat = (context, accountKey, chat) => {
     })
         .run();
 };
+const mergedMetadata = (stored, incoming) => {
+    if (incoming === undefined)
+        return stored;
+    const merged = Object.entries({ ...metadataObject(stored), ...incoming }).filter(([, value]) => value !== null);
+    return merged.length === 0 ? null : JSON.stringify(Object.fromEntries(merged));
+};
+// Stored metadata that is not an object has no keys to keep.
+const metadataObject = (stored) => {
+    try {
+        const value = stored === null ? null : JSON.parse(stored);
+        return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+    }
+    catch {
+        return {};
+    }
+};
 /** Replaces who is in the chat, whole. */
 export const writeMembers = (context, key, accountKey, chatId, memberIds) => {
     const chatKey = chatPkFor(context, accountKey, chatId);

package/dist/terminal/login-qr.d.ts

@@ -0,0 +1,27 @@
+import { CliError } from "@wirecat/cli-base";
+/** Whether a person can scan a code drawn here and answer what the login asks next. */
+export declare const atTerminal: (input: NodeJS.ReadableStream & {
+    isTTY?: boolean;
+}) => boolean;
+/** The one refusal of a QR login that nobody could scan. */
+export declare const qrNeedsTerminal: (command: string) => CliError;
+export interface LoginQrOptions {
+    /** `--qr-file`: the PNG to write instead of drawing the code. */
+    qrFile?: string;
+    /** Where the code and the narrow-terminal hint go; `--quiet` must not hide either. */
+    diagnostic: (text: string) => void;
+    /** Where the file's location is said. */
+    note: (text: string) => void;
+    /** How far the code sits right, to line up under a setup step. */
+    indent?: number;
+    /** Read on every code, so a widened terminal draws the next one. Unknown draws the code. */
+    columns?: () => number | undefined;
+}
+export interface LoginQr {
+    readonly path: string | undefined;
+    /** Never throws for a code that does not fit: the messengers call it from inside their own event loops. */
+    show: (link: string) => void;
+    /** The image logs the account in while it is valid; call this in `finally`. */
+    close: () => void;
+}
+export declare const loginQr: ({ qrFile, diagnostic, note, indent: pad, columns, }: LoginQrOptions) => LoginQr;

package/dist/terminal/login-qr.js

@@ -0,0 +1,44 @@
+import { rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { CliError, indent, writeSecurely } from "@wirecat/cli-base";
+import { inputPolicy } from "../cli/input-policy.js";
+import { qrPng, terminalQr } from "./qr.js";
+const MARGIN = 2;
+/** Whether a person can scan a code drawn here and answer what the login asks next. */
+export const atTerminal = (input) => input.isTTY === true && !inputPolicy(input).noInput;
+/** The one refusal of a QR login that nobody could scan. */
+export const qrNeedsTerminal = (command) => new CliError("validation_error", `${command} shows a QR code to scan — run it in a terminal, or pass --qr-file <png>`, {
+    param: "--qr-file",
+    reason: "input.required",
+});
+export const loginQr = ({ qrFile, diagnostic, note, indent: pad = 0, columns = () => process.stderr.columns, }) => {
+    const path = qrFile === undefined ? undefined : resolve(qrFile);
+    // Only what this login wrote is removed: a refused or never-reached write leaves the owner's file alone.
+    let written = false;
+    return {
+        path,
+        show: (link) => {
+            if (path) {
+                writeSecurely(path, qrPng(link), 0o600);
+                written = true;
+                note(`the QR code is in ${path} — it is replaced when the code renews`);
+                return;
+            }
+            const drawn = terminalQr(link);
+            const need = drawn.width + pad + MARGIN;
+            const width = columns();
+            if (width !== undefined && need > width) {
+                diagnostic(`the terminal is ${width} columns wide and the QR code needs ${need} — widen it, ` +
+                    "or run again with --qr-file <png>");
+                return;
+            }
+            diagnostic(`\n${indent(drawn.text, pad + MARGIN)}`);
+        },
+        close: () => {
+            if (!path || !written)
+                return;
+            written = false;
+            rmSync(path, { force: true });
+        },
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.345.0",
+  "version": "0.347.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",

package/parity.json

@@ -2847,6 +2847,14 @@
         "wa": "wa backlog: mount the shared flood command"
       }
     },
+    "guide": {
+      "in": [],
+      "planned": {
+        "max": "help-navigation pass: max-cli#737 mounts guide with scenarios",
+        "tg": "help-navigation pass: mount guide with scenarios",
+        "wa": "help-navigation pass: mount guide with scenarios"
+      }
+    },
     "images": {
       "in": "all"
     },
@@ -4047,7 +4055,9 @@
         },
         "--qr-file": {
           "in": ["tg", "wa"],
-          "reason": "ruled tg-only with the app registration it belongs to"
+          "planned": {
+            "max": "max-cli#736, on the cli-core release that exports loginQr"
+          }
         },
         "--sms": {
           "in": ["tg"],
@@ -4066,7 +4076,9 @@
         "--method": "all",
         "--qr-file": {
           "in": ["tg", "wa"],
-          "reason": "Telegram can expose its temporary QR login token as a PNG"
+          "planned": {
+            "max": "max-cli#736, on the cli-core release that exports loginQr"
+          }
         }
       }
     },