herdrchat 1.3.3 → 1.4.1

package/lib/chats/feishu/client.mjs

@@ -102,14 +102,24 @@ function button(text, value, type = 'default') {
   return { tag: 'button', type, width: 'fill', text: { tag: 'plain_text', content: short }, behaviors: [{ type: 'callback', value }] };
 }
 
+// A multi-select's boxes are checkers in a form: with no behaviors a checker is ticked on
+// the phone only, so ticking makes no call and shows no loading; Next submits the form,
+// and each box comes back in form_value under its name, box_<n> (ticksOf reads them).
+export const BOX = 'box_';
 export function menuCard({ title, markdown, menu, value }) {
   const elements = [{ tag: 'markdown', content: markdown }];
+  const boxes = [];
   for (const o of menu.options) {
     if (o === menu.free) continue;
-    const box = o.checked === null ? '' : o.checked ? '☑ ' : '☐ ';
-    elements.push(button(`${o.n}. ${box}${o.label}`, { ...value, pick: o.n, label: o.label }, o.n === 1 && !menu.multi ? 'primary' : 'default'));
+    if (menu.multi && o.checked !== null) {
+      boxes.push({ tag: 'checker', name: `${BOX}${o.n}`, checked: o.checked, text: { tag: 'plain_text', content: `${o.n}. ${o.label}` } });
+      continue;
+    }
+    elements.push(button(`${o.n}. ${o.label}`, { ...value, pick: o.n, label: o.label }, o.n === 1 && !menu.multi ? 'primary' : 'default'));
+  }
+  if (menu.multi) {
+    elements.push({ tag: 'form', name: 'boxes', elements: [...boxes, { ...button('Next ⇥', { ...value, pick: 'tab' }, 'primary'), name: 'next', form_action_type: 'submit' }] });
   }
-  if (menu.multi) elements.push(button('Next ⇥', { ...value, pick: 'tab' }, 'primary'));
   if (menu.free) {
     elements.push({
       tag: 'form',
@@ -174,8 +184,16 @@ export async function downloadImage(client, messageId, imageKey, file) {
 
 // What a received message says: its text and the keys of its images, in order, for
 // text, image and rich text (post) messages; null for any other kind.
+// null for what is not passed on: another type (a file, forwarded chat records, ...), or a
+// content that is not JSON (a merged forward lists as "Merged and Forwarded Message").
 export function messageParts(messageType, content) {
-  const c = JSON.parse(content);
+  let c;
+  try {
+    c = JSON.parse(content);
+  } catch {
+    return null;
+  }
+  if (!c || typeof c !== 'object') return null;
   if (messageType === 'text') return { text: c.text || '', images: [] };
   if (messageType === 'image') return { text: '', images: [c.image_key] };
   if (messageType !== 'post') return null;
@@ -306,3 +324,12 @@ export function startEvents(cfg, onMessage, onCardAction, onReady = () => {}, on
   });
   return ws;
 }
+
+// The boxes as ticked, from a submitted form: {<n>: true|false}, or null when form_value
+// has none of them (then nothing can be known, and nothing should be pressed). A checker's
+// value is read as true when it is true or "true".
+export function ticksOf(formValue) {
+  const entries = Object.entries(formValue || {}).filter(([name]) => name.startsWith(BOX));
+  if (!entries.length) return null;
+  return Object.fromEntries(entries.map(([name, v]) => [Number(name.slice(BOX.length)), v === true || v === 'true']));
+}

package/lib/chats/feishu/index.mjs

@@ -1,15 +1,14 @@
-// herdrchat's Feishu side: one group per tab (a "room" to the core), the direct chat with
-// the bot for the overview and commands, and what only Feishu has: tenant tags, group
-// avatars, and, after /auth, acting as you (muted groups, your labels, pins, @ mentions).
-// The core (lib/core/engine.mjs) calls only what is returned here; see "The chat side"
-// there for what each call means.
-import { createClient, bindTag, chunk, createChat, createTag, doneCard, downloadImage, foldedCard, menuCard, messageParts, recallMessage, renameChat, replyMention, sendCard, sendFile, sendMarkdown, setChatAvatar, startEvents, tagName, textCard, unbindTag, updateCard, uploadImage } from './client.mjs';
-import { COLORS, avatarPng, letterOf } from './avatar.mjs';
+// herdrchat's Feishu side: the rooms (rooms/: how tabs are laid out in groups, and what a
+// group wears), the direct chat with the bot for the overview and commands, and, after
+// /auth, acting as you (muted groups, your labels, pins, @ mentions). The core
+// (lib/core/engine.mjs) calls only what is returned here; see "The chat side" there for
+// what each call means.
+import { ticksOf, createClient, chunk, doneCard, downloadImage, foldedCard, menuCard, messageParts, recallMessage, sendCard, sendFile, sendMarkdown, startEvents, textCard, updateCard, uploadImage } from './client.mjs';
 import { overviewCard, overviewText } from './overview.mjs';
 import { createUserAuth } from './userauth.mjs';
+import { createDecor } from './rooms/decor.mjs';
+import { createGroups } from './rooms/groups.mjs';
 
-const ENDED_TAG = '#ended';
-const ENDED_LABEL = 'ended';
 const YOU_CHECK_MS = 60 * 1000;
 const OVERVIEW_TRIES = 3;
 const WORKING_EMOJI = 'THINKING';
@@ -20,123 +19,16 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // What to do after an edit to config.env, said the way this profile is run.
 const startAgain = (cfg) => `\`herdrchat start${cfg.profile && cfg.profile !== 'default' ? ` --profile ${cfg.profile}` : ''}\``;
 
-const inSpaces = (set, space) => set.all || set.spaces.includes(space);
-const spaceOfName = (name) => (name || '').split(' / ')[0];
-
 // cfg: loadConfig(); store: {read, write} of state.json; lane(k, label, fn): runs fn in
 // the room's lane, after what is queued for it; scopeOf(k): the session or machine a
 // room's terminal belongs to (its tag and label).
 export const requires = ['FEISHU_APP_ID', 'FEISHU_APP_SECRET'];
 
-export function create({ cfg, store, log, logWarn, logError, stateDir, lane, scopeOf }) {
+export function create({ cfg, store, log, logWarn, logError, stateDir, lane, scopeOf, claimOwner = () => 'none' }) {
   const client = createClient(cfg);
   const userAuth = createUserAuth(cfg, stateDir);
   const { read, write } = store;
 
-  function setRoom(k, fields) {
-    const state = read();
-    if (state.chats[k]) state.chats[k] = { ...state.chats[k], ...fields };
-    write(state);
-  }
-
-  // Lanes run side by side: a thing that is made once (a tag, a space's avatar) is made
-  // by the first lane that needs it; the others wait for that.
-  const making = new Map();
-  function once(id, make) {
-    if (!making.has(id)) making.set(id, make().finally(() => making.delete(id)));
-    return making.get(id);
-  }
-
-  // ---------- tags and avatars ----------
-
-  // One tenant tag per session or machine, made once, and one "ended" tag; their ids are
-  // kept in state.json (tags).
-  async function tagOf(id, name = id) {
-    return read().tags?.[id] || once(`tag ${id}`, async () => {
-      const tag = await createTag(client, name);
-      const state = read();
-      state.tags = { ...(state.tags || {}), [id]: tag };
-      write(state);
-      log(`created tag ${name} (${tag})`);
-      return tag;
-    });
-  }
-
-  // Each space gets an avatar: its first letter on a color of its own (the first color no
-  // other space has), kept in state.json (spaces), so all of its groups look alike, as in
-  // herdr-app. The color is picked and saved before the first await, so spaces made side
-  // by side never pick the same one. A failure is logged and tried again at the next check.
-  function colorOf(space) {
-    const state = read();
-    const spaces = state.spaces || {};
-    if (spaces[space]?.color) return spaces[space].color;
-    const used = Object.values(spaces).map((x) => x.color);
-    const color = COLORS.find((c) => !used.includes(c)) || COLORS[used.length % COLORS.length];
-    state.spaces = { ...spaces, [space]: { color } };
-    write(state);
-    return color;
-  }
-
-  async function avatarOf(space) {
-    return read().spaces?.[space]?.image || once(`avatar ${space}`, async () => {
-      const color = colorOf(space);
-      const image = await uploadImage(client, await avatarPng(letterOf(space), color), 'avatar');
-      const state = read();
-      state.spaces = { ...(state.spaces || {}), [space]: { color, image } };
-      write(state);
-      log(`made avatar for space ${space} (${color})`);
-      return image;
-    });
-  }
-
-  // the space's avatar; a no-op when the group has it, so it follows a space that changes
-  async function avatarRoom(k, space) {
-    const c = read().chats[k];
-    if (!c) return;
-    try {
-      const image = await avatarOf(space);
-      if (c.avatar === image) return;
-      await setChatAvatar(client, c.chat, image);
-      setRoom(k, { avatar: image });
-    } catch (err) {
-      logError(`avatar ${space} on ${c.chat}: ${err.message}`);
-    }
-  }
-
-  // Bot tags (HERDR_BOT_TAGS): the session or machine tag next to a group's name and, once
-  // its terminal is gone, "ended". They are tenant tags, so they can be turned off; off
-  // takes off the ones already on. A failure is logged and tried again at the next check.
-  async function syncBotTags(k, scope) {
-    const c = read().chats[k];
-    if (!c) return;
-    try {
-      if (cfg.botTags) {
-        const tag = await tagOf(scope);
-        if (c.tag !== tag) {
-          await bindTag(client, tag, c.chat);
-          setRoom(k, { tag });
-        }
-        if (Boolean(c.ended) !== Boolean(c.endedTag)) {
-          const ended = await tagOf(ENDED_TAG, 'ended');
-          await (c.ended ? bindTag : unbindTag)(client, ended, c.chat);
-          setRoom(k, { endedTag: Boolean(c.ended) });
-        }
-      } else {
-        const tags = read().tags || {};
-        if (c.tag) {
-          await unbindTag(client, c.tag, c.chat).catch(() => {});
-          setRoom(k, { tag: null });
-        }
-        if (c.endedTag && tags[ENDED_TAG]) {
-          await unbindTag(client, tags[ENDED_TAG], c.chat).catch(() => {});
-          setRoom(k, { endedTag: false });
-        }
-      }
-    } catch (err) {
-      logError(`bot tags on ${c.name}: ${err.message}`);
-    }
-  }
-
   // ---------- acting as you (optional, after /auth) ----------
 
   // With your token (userauth.mjs) the bot does what only you can: mutes its groups,
@@ -156,7 +48,7 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
     you = await userAuth.allowed();
     if (you && !was) {
       log('acting as you: on');
-      setTimeout(alignAll, 0);
+      setTimeout(() => rooms.alignAll(), 0);
     } else if (!you && was) {
       logWarn('acting as you: off');
       await tellOwner({ title: '⚠️ Needs you', tone: 'needs', markdown: 'The bot can no longer act as you (mute, labels, pin). Send `/auth` to allow it again.' }).catch(() => {});
@@ -164,107 +56,10 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
     return you;
   }
 
-  async function labelOf(name) {
-    return read().labels?.[name] || once(`label ${name}`, async () => {
-      const found = (await userAuth.feedGroups())?.groups?.find((g) => g.name === name);
-      const id = found?.group_id || (await userAuth.createFeedGroup(name))?.group_id;
-      if (!id) throw new Error(`no label ${name}`);
-      const state = read();
-      state.labels = { ...(state.labels || {}), [name]: id };
-      write(state);
-      log(`label ${name} (${id})`);
-      return id;
-    });
-  }
-
-  // A label you deleted is made again at the next try.
-  async function intoLabel(name, chat) {
-    try {
-      await userAuth.addToFeedGroup(await labelOf(name), [chat]);
-    } catch (err) {
-      const state = read();
-      if (state.labels) delete state.labels[name];
-      write(state);
-      throw err;
-    }
-  }
-
-  // Your label (HERDR_USER_TAGS, acting as you): the session or machine, or "ended" once
-  // the terminal is gone; off takes the group out of it (the label itself is yours).
-  async function syncUserLabel(k, scope) {
-    if (!(await asYou())) return;
-    const c = read().chats[k];
-    if (!c) return;
-    const want = cfg.userTags ? (c.ended ? ENDED_LABEL : tagName(scope)) : null;
-    if ((c.label || null) === want) return;
-    try {
-      if (c.label) await userAuth.removeFromFeedGroup(await labelOf(c.label), [c.chat]).catch(() => {});
-      if (want) await intoLabel(want, c.chat);
-      setRoom(k, { label: want });
-    } catch (err) {
-      logError(`as you, label of ${c.name}: ${err.message}`);
-    }
-  }
-
-  // HERDR_MUTED_SPACES says which groups are muted (all, none, or some spaces); a change
-  // in config.env is applied both ways at the next start.
-  async function muteRoom(k, space) {
-    const c = read().chats[k];
-    const want = inSpaces(cfg.muted, space);
-    if (!c || Boolean(c.muted) === want) return;
-    try {
-      await userAuth.setMuted([c.chat], want);
-      setRoom(k, { muted: want });
-    } catch (err) {
-      logError(`as you, mute ${c.chat}: ${err.message}`);
-    }
-  }
-
-  // Everything at once, when acting as you turns on: live groups to their labels, ended
-  // ones to "ended".
-  function alignAll() {
-    for (const [k, c] of Object.entries(read().chats)) {
-      if (!cfg.sessions.includes(c.session)) continue;
-      lane(k, 'as you', () => (c.ended ? endRoom(k) : placeRoom(k, { space: spaceOfName(c.name) })));
-    }
-  }
-
   // ---------- rooms ----------
 
-  // One group per tab, with you in it; what you type there goes to its terminal.
-  async function openRoom({ name, intro }) {
-    return createChat(client, cfg.ownerOpenId, name, intro);
-  }
-
-  async function renameRoom(room, name) {
-    await renameChat(client, room, name);
-  }
-
-  // Puts a live group where it belongs: its avatar, its bot tag and, acting as you, muted
-  // and in your label. Cheap when nothing is left to do.
-  async function placeRoom(k, { space }) {
-    await avatarRoom(k, space);
-    await syncBotTags(k, scopeOf(k));
-    if (!(await asYou())) return;
-    await muteRoom(k, space);
-    await syncUserLabel(k, scopeOf(k));
-  }
-
-  // A group whose terminal is gone keeps its history, tagged "ended".
-  async function endRoom(k) {
-    const c = read().chats[k];
-    if (!c) return;
-    await syncBotTags(k, scopeOf(k));
-    if (!c.avatar) await avatarRoom(k, spaceOfName(c.name));
-    if (!(await asYou())) return;
-    await muteRoom(k, spaceOfName(c.name));
-    await syncUserLabel(k, scopeOf(k));
-  }
-
-  async function reviveRoom(k) {
-    await syncBotTags(k, scopeOf(k));
-    await syncUserLabel(k, scopeOf(k));
-  }
+  const decor = createDecor({ client, cfg, store, log, logError, userAuth, asYou });
+  const rooms = createGroups({ client, cfg, store, logError, lane, scopeOf, userAuth, asYou, decor });
 
   // ---------- posting ----------
 
@@ -289,43 +84,6 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
     await updateCard(client, message, doneCard(dialog.doneTitle, dialog.markdown, done));
   }
 
-  // The group that needs you is pinned while it waits (acting as you), and unpinned when
-  // it no longer does; which ones are pinned is kept in state.json (pinned).
-  async function pin(k, room) {
-    if (!(await asYou())) return;
-    try {
-      await userAuth.pin(room);
-      const state = read();
-      state.pinned = { ...(state.pinned || {}), [k]: room };
-      write(state);
-    } catch (err) {
-      logError(`pin ${room}: ${err.message}`);
-    }
-  }
-
-  async function unpin(k) {
-    const room = read().pinned?.[k];
-    if (!room) return;
-    try {
-      await userAuth.unpin(room);
-    } catch (err) {
-      logError(`unpin ${room}: ${err.message}`);
-    }
-    const state = read();
-    delete state.pinned[k];
-    write(state);
-  }
-
-  const pinned = () => Object.keys(read().pinned || {});
-
-  // In a muted group only a mention rings; a group that is not muted rings anyway. A
-  // space in HERDR_SILENT_SPACES gets no mention at all.
-  async function ring(k, message, text) {
-    const c = read().chats[k];
-    if (!message || !c?.muted || inSpaces(cfg.silent, spaceOfName(c.name)) || !(await asYou())) return;
-    await replyMention(client, message, cfg.ownerOpenId, text).catch((err) => logError(`mention: ${err.message}`));
-  }
-
   async function addReaction(message, emoji) {
     const res = await client.im.v1.messageReaction.create({ path: { message_id: message }, data: { reaction_type: { emoji_type: emoji } } });
     return res?.data?.reaction_id;
@@ -432,7 +190,14 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
       seen.add(msg.message_id);
       if (seen.size > 2000) seen.delete(seen.values().next().value);
       queued(msg.chat_id, async () => {
-        await handleMessage(data);
+        // whatever goes wrong, you are told it did not get through, and it is not tried
+        // again at every connection
+        try {
+          await handleMessage(data);
+        } catch (err) {
+          logError(`feishu message ${msg.message_id} in ${msg.chat_id}:`, err);
+          if (data.sender?.sender_id?.open_id === cfg.ownerOpenId) await reply(msg.chat_id, `⚠️ Not delivered: it could not be handled (${err.message}). Send it again; \`herdrchat logs\` has the details.`).catch(() => {});
+        }
         markRead(msg.chat_id, Number(msg.create_time) || Date.now());
       });
     };
@@ -440,8 +205,13 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
       const msg = data.message;
       const openId = data.sender?.sender_id?.open_id;
       if (!cfg.ownerOpenId) {
-        log(`owner not set; message from open_id ${openId}`);
-        if (msg.chat_type === 'p2p') await reply(msg.chat_id, `Hello! To make you this bot's owner (the only person it listens to), add this line to ${cfg.configFile || 'config.env'}:\n\n\`FEISHU_OWNER_OPEN_ID=${openId}\`\n\nthen run ${startAgain(cfg)}. Your terminals' groups appear then.`);
+        if (msg.chat_type !== 'p2p') return;
+        const said = messageParts(msg.message_type, msg.content)?.text || '';
+        const paired = said.trim().startsWith('/') ? 'none' : claimOwner(said, 'FEISHU_OWNER_OPEN_ID', openId);
+        log(`owner not set; message from open_id ${openId} (pairing: ${paired})`);
+        if (paired === 'ok') await reply(msg.chat_id, '✅ Paired: you are this bot\'s owner now. It starts again, and your terminals\' groups appear in a moment.\n\nThen: type in a terminal\'s group to talk to it; here, /ls shows them all, /new starts one, /auth lets the bot mute its groups.');
+        else if (paired === 'wrong') await reply(msg.chat_id, 'That is not the code. Send the 6 digits `herdrchat setup` shows.');
+        else await reply(msg.chat_id, `Hello! This bot has no owner yet. Run \`herdrchat setup${cfg.profile && cfg.profile !== 'default' ? ` --profile ${cfg.profile}` : ''}\` and send me the code it shows; or add this line to ${cfg.configFile || 'config.env'} yourself and run ${startAgain(cfg)}:\n\n\`FEISHU_OWNER_OPEN_ID=${openId}\``);
         return;
       }
       if (openId !== cfg.ownerOpenId) {
@@ -450,18 +220,28 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
       }
       const parts = messageParts(msg.message_type, msg.content);
       if (!parts) {
-        await reply(msg.chat_id, 'Only text and images are passed on.');
+        await reply(msg.chat_id, `Not delivered: only text and images are passed on, not this (${msg.message_type}). Copy its text into a message.`);
         return;
       }
       const text = parts.text.replace(/@_user_\d+/g, '').trim();
       if (!text && !parts.images.length) return;
-      await onMessage({ room: msg.chat_type === 'p2p' ? null : msg.chat_id, where: msg.chat_id, message: msg.message_id, text, images: parts.images });
+      await onMessage({ room: rooms.roomOf(msg), where: msg.chat_id, message: msg.message_id, text, images: parts.images });
     };
     // A click must be answered within 3 seconds; the core's answer becomes Feishu's
     // callback response: a toast and, when the card changes, its new form.
     const handleAction = async (data) => {
       if (data.operator?.open_id !== cfg.ownerOpenId) return { toast: { type: 'error', content: 'Only the owner can answer.' } };
-      const out = await onAction({ value: data.action?.value || {}, message: data.context?.open_message_id, answer: String(data.action?.form_value?.answer || '') });
+      const value = data.action?.value || {};
+      const form = data.action?.form_value;
+      let ticks = null;
+      if (value.pick === 'tab' && form) {
+        ticks = ticksOf(form);
+        // what each box sent, by type only (never what it says): to see the shape Feishu uses
+        log(`card form: ${Object.entries(form).map(([n, v]) => `${n}=${typeof v}:${typeof v === 'boolean' ? v : String(v).length}`).join(' ') || 'empty'}`);
+        // no box came back: the ticks are unknown, and a wrong answer is worse than none
+        if (!ticks) return { toast: { type: 'error', content: 'No ticked box came through, so nothing was sent. Tick at least one, or answer it in herdr-app.' } };
+      }
+      const out = await onAction({ value, message: data.context?.open_message_id, answer: String(form?.answer || ''), ticks });
       const res = { toast: { type: out.toast.type, content: out.toast.text } };
       if (out.card?.kind === 'done') res.card = { type: 'raw', data: doneCard(out.card.dialog.doneTitle, out.card.dialog.markdown, out.card.done) };
       if (out.card?.kind === 'dialog') res.card = { type: 'raw', data: menuCard({ title: out.card.dialog.title, markdown: out.card.dialog.markdown, menu: out.card.dialog.menu, value: out.card.value }) };
@@ -472,7 +252,7 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
     const catchUp = async () => {
       if (!cfg.ownerOpenId) return;
       const state = read();
-      const chats = new Set([...Object.values(state.chats || {}).filter((c) => !c.ended).map((c) => c.chat), ...Object.keys(state.feishuRead || {})]);
+      const chats = new Set([...rooms.roomChats(), ...Object.keys(state.feishuRead || {})]);
       for (const chatId of chats) {
         const since = state.feishuRead?.[chatId];
         if (!since) {
@@ -483,8 +263,8 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
           const res = await client.im.v1.message.list({ params: { container_id_type: 'chat', container_id: chatId, start_time: String(Math.floor(since / 1000)), sort_type: 'ByCreateTimeAsc', page_size: 50 } });
           const missed = (res?.data?.items || []).filter((m) => Number(m.create_time) > since && m.sender?.sender_type === 'user' && m.sender?.id === cfg.ownerOpenId && !seen.has(m.message_id));
           if (missed.length) log(`feishu: ${missed.length} message(s) in ${chatId} came while the bot was away`);
-          const p2p = !Object.values(state.chats || {}).some((c) => c.chat === chatId);
-          for (const m of missed) take({ message: { message_id: m.message_id, chat_id: chatId, chat_type: p2p ? 'p2p' : 'group', message_type: m.msg_type, content: m.body?.content || '{}', create_time: m.create_time }, sender: { sender_id: { open_id: m.sender.id } } });
+          const p2p = !rooms.isRoomChat(chatId);
+          for (const m of missed) take({ message: { message_id: m.message_id, chat_id: chatId, chat_type: p2p ? 'p2p' : 'group', root_id: m.root_id, thread_id: m.thread_id, message_type: m.msg_type, content: m.body?.content || '{}', create_time: m.create_time }, sender: { sender_id: { open_id: m.sender.id } } });
         } catch (err) {
           logWarn(`feishu: could not look for missed messages in ${chatId}: ${err.message}`);
         }
@@ -529,25 +309,25 @@ export function create({ cfg, store, log, logWarn, logError, stateDir, lane, sco
     name: 'feishu',
     ready: () => Boolean(cfg.ownerOpenId),
     help: ['`/auth` let the bot act as you for chat-list settings (mute, labels, pin)'],
-    roomWord: 'group',
+    roomWord: rooms.roomWord,
     liveBytes: 20000, // a card may hold 30 KB; room for JSON escaping
     split: (text) => chunk(text),
     start,
     command,
-    openRoom,
-    renameRoom,
-    placeRoom,
-    endRoom,
-    reviveRoom,
+    openRoom: rooms.openRoom,
+    renameRoom: rooms.renameRoom,
+    placeRoom: rooms.placeRoom,
+    endRoom: rooms.endRoom,
+    reviveRoom: rooms.reviveRoom,
     post,
     postCard,
     editCard,
     postDialog,
     closeDialog,
-    pin,
-    unpin,
-    pinned,
-    ring,
+    pin: rooms.pin,
+    unpin: rooms.unpin,
+    pinned: rooms.pinned,
+    ring: rooms.ring,
     markWorking,
     markDone,
     image,

package/lib/chats/feishu/rooms/decor.mjs

@@ -0,0 +1,175 @@
+// What a Feishu group wears, whichever way rooms are laid out (groups.mjs: one group per
+// tab; a space's group, later): the space's avatar, the bot tags, and, acting as you, your
+// label and its mute. Each call takes an `entry`, {get() -> record, set(fields)}: the record
+// of the group in state.json, {chat, name, avatar, tag, ended, endedTag, label, muted}.
+import { bindTag, createTag, setChatAvatar, tagName, unbindTag, uploadImage } from '../client.mjs';
+import { COLORS, avatarPng, letterOf } from '../avatar.mjs';
+
+const ENDED_TAG = '#ended';
+const ENDED_LABEL = 'ended';
+
+export const inSpaces = (set, space) => set.all || set.spaces.includes(space);
+export const spaceOfName = (name) => (name || '').split(' / ')[0];
+
+// asYou() -> whether the bot may act as you now (index.mjs keeps that)
+export function createDecor({ client, cfg, store, log, logError, userAuth, asYou }) {
+  const { read, write } = store;
+
+  // Lanes run side by side: a thing that is made once (a tag, a space's avatar) is made
+  // by the first lane that needs it; the others wait for that.
+  const making = new Map();
+  function once(id, make) {
+    if (!making.has(id)) making.set(id, make().finally(() => making.delete(id)));
+    return making.get(id);
+  }
+
+  // ---------- tags and avatars ----------
+
+  // One tenant tag per session or machine, made once, and one "ended" tag; their ids are
+  // kept in state.json (tags).
+  async function tagOf(id, name = id) {
+    return read().tags?.[id] || once(`tag ${id}`, async () => {
+      const tag = await createTag(client, name);
+      const state = read();
+      state.tags = { ...(state.tags || {}), [id]: tag };
+      write(state);
+      log(`created tag ${name} (${tag})`);
+      return tag;
+    });
+  }
+
+  // Each space gets an avatar: its first letter on a color of its own (the first color no
+  // other space has), kept in state.json (spaces), so all of its groups look alike, as in
+  // herdr-app. The color is picked and saved before the first await, so spaces made side
+  // by side never pick the same one. A failure is logged and tried again at the next check.
+  function colorOf(space) {
+    const state = read();
+    const spaces = state.spaces || {};
+    if (spaces[space]?.color) return spaces[space].color;
+    const used = Object.values(spaces).map((x) => x.color);
+    const color = COLORS.find((c) => !used.includes(c)) || COLORS[used.length % COLORS.length];
+    state.spaces = { ...spaces, [space]: { color } };
+    write(state);
+    return color;
+  }
+
+  async function avatarOf(space) {
+    return read().spaces?.[space]?.image || once(`avatar ${space}`, async () => {
+      const color = colorOf(space);
+      const image = await uploadImage(client, await avatarPng(letterOf(space), color), 'avatar');
+      const state = read();
+      state.spaces = { ...(state.spaces || {}), [space]: { color, image } };
+      write(state);
+      log(`made avatar for space ${space} (${color})`);
+      return image;
+    });
+  }
+
+  // the space's avatar; a no-op when the group has it, so it follows a space that changes
+  async function avatar(entry, space) {
+    const c = entry.get();
+    if (!c) return;
+    try {
+      const image = await avatarOf(space);
+      if (c.avatar === image) return;
+      await setChatAvatar(client, c.chat, image);
+      entry.set({ avatar: image });
+    } catch (err) {
+      logError(`avatar ${space} on ${c.chat}: ${err.message}`);
+    }
+  }
+
+  // Bot tags (HERDR_BOT_TAGS): the session or machine tag next to a group's name and, once
+  // its terminal is gone, "ended". They are tenant tags, so they can be turned off; off
+  // takes off the ones already on. A failure is logged and tried again at the next check.
+  async function botTags(entry, scope) {
+    const c = entry.get();
+    if (!c) return;
+    try {
+      if (cfg.botTags) {
+        const tag = await tagOf(scope);
+        if (c.tag !== tag) {
+          await bindTag(client, tag, c.chat);
+          entry.set({ tag });
+        }
+        if (Boolean(c.ended) !== Boolean(c.endedTag)) {
+          const ended = await tagOf(ENDED_TAG, 'ended');
+          await (c.ended ? bindTag : unbindTag)(client, ended, c.chat);
+          entry.set({ endedTag: Boolean(c.ended) });
+        }
+      } else {
+        const tags = read().tags || {};
+        if (c.tag) {
+          await unbindTag(client, c.tag, c.chat).catch(() => {});
+          entry.set({ tag: null });
+        }
+        if (c.endedTag && tags[ENDED_TAG]) {
+          await unbindTag(client, tags[ENDED_TAG], c.chat).catch(() => {});
+          entry.set({ endedTag: false });
+        }
+      }
+    } catch (err) {
+      logError(`bot tags on ${c.name}: ${err.message}`);
+    }
+  }
+
+  // ---------- acting as you ----------
+
+  async function labelOf(name) {
+    return read().labels?.[name] || once(`label ${name}`, async () => {
+      const found = (await userAuth.feedGroups())?.groups?.find((g) => g.name === name);
+      const id = found?.group_id || (await userAuth.createFeedGroup(name))?.group_id;
+      if (!id) throw new Error(`no label ${name}`);
+      const state = read();
+      state.labels = { ...(state.labels || {}), [name]: id };
+      write(state);
+      log(`label ${name} (${id})`);
+      return id;
+    });
+  }
+
+  // A label you deleted is made again at the next try.
+  async function intoLabel(name, chat) {
+    try {
+      await userAuth.addToFeedGroup(await labelOf(name), [chat]);
+    } catch (err) {
+      const state = read();
+      if (state.labels) delete state.labels[name];
+      write(state);
+      throw err;
+    }
+  }
+
+  // Your label (HERDR_USER_TAGS, acting as you): the session or machine, or "ended" once
+  // the terminal is gone; off takes the group out of it (the label itself is yours).
+  async function userLabel(entry, scope) {
+    if (!(await asYou())) return;
+    const c = entry.get();
+    if (!c) return;
+    const want = cfg.userTags ? (c.ended ? ENDED_LABEL : tagName(scope)) : null;
+    if ((c.label || null) === want) return;
+    try {
+      if (c.label) await userAuth.removeFromFeedGroup(await labelOf(c.label), [c.chat]).catch(() => {});
+      if (want) await intoLabel(want, c.chat);
+      entry.set({ label: want });
+    } catch (err) {
+      logError(`as you, label of ${c.name}: ${err.message}`);
+    }
+  }
+
+  // HERDR_MUTED_SPACES says which groups are muted (all, none, or some spaces); a change
+  // in config.env is applied both ways at the next start.
+  async function mute(entry, space) {
+    const c = entry.get();
+    const want = inSpaces(cfg.muted, space);
+    if (!c || Boolean(c.muted) === want) return;
+    try {
+      await userAuth.setMuted([c.chat], want);
+      entry.set({ muted: want });
+    } catch (err) {
+      logError(`as you, mute ${c.chat}: ${err.message}`);
+    }
+  }
+
+  return { avatar, botTags, userLabel, mute };
+}