@wirecat/cli-core 0.345.0 → 0.346.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ shape of this file.
 
 ## Unreleased
 
+## 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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.345.0",
+  "version": "0.346.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",