slack-term 1.19.1 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slack-term",
-  "version": "1.19.1",
+  "version": "1.21.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/snomiao/slack-term.git"

package/ts/cli.ts

@@ -24,6 +24,9 @@ import {
   updateDraft,
   editMessage,
   deleteMessage,
+  reactionAdd,
+  reactionRemove,
+  filesInfo,
   history,
   listConversations,
   listDrafts,
@@ -48,7 +51,7 @@ import {
   getPath,
   type Json,
 } from "./slack.ts";
-import { dayLabel, encodeMentions, formatYmdHm, resolveDateMarkup, resolveMentions } from "./format.ts";
+import { dayLabel, encodeMentions, findUntaggedMentions, formatYmdHm, resolveDateMarkup, resolveMentions } from "./format.ts";
 
 function loadDotenv(path: string): void {
   if (!existsSync(path)) return;
@@ -186,14 +189,44 @@ async function formatMsgLine(
     })
     .filter(Boolean)
     .join(" ");
-  const tail = reactions ? `\n   ${reactions}` : "";
+  const attachTail = asArray(m.files)
+    .map(asRecord)
+    .map((f) => {
+      const name = typeof f.name === "string" ? f.name : typeof f.title === "string" ? f.title : "(file)";
+      const sz = typeof f.size === "number" ? `  (${fmtSize(f.size)})` : "";
+      const id = typeof f.id === "string" ? `  [${f.id}]` : "";
+      return `\n   📎 ${name}${sz}${id}`;
+    })
+    .join("");
+  const tail = (reactions ? `\n   ${reactions}` : "") + attachTail;
   return `${stamp}  ${who}:  ${body}${tail}`;
 }
 
+// Human-readable byte size, shared by upload/download/attachment rendering.
+function fmtSize(n: number): string {
+  return n < 1024 ? `${n} B` : n < 1048576 ? `${(n / 1024).toFixed(1)} KB` : `${(n / 1048576).toFixed(1)} MB`;
+}
+
+// Slim a message's file attachments to the fields a script needs to detect and
+// fetch them: id (for `slack download`), name, size, mimetype, and the two URLs.
+function slimFiles(m: Record<string, Json>): Record<string, Json>[] {
+  return asArray(m.files)
+    .map(asRecord)
+    .map((f) => ({
+      id: f.id ?? null,
+      name: f.name ?? f.title ?? null,
+      mimetype: f.mimetype ?? null,
+      size: f.size ?? null,
+      url_private_download: f.url_private_download ?? f.url_private ?? null,
+      permalink: f.permalink ?? null,
+    }));
+}
+
 // Slim a raw message down to the fields a script actually needs. Keeps the
 // author's user ID (incl. external / Slack-Connect guests that never appear in
 // users.list) so callers can resolve mentions without scraping history by hand.
 function slimMsg(m: Record<string, Json>): Record<string, Json> {
+  const files = slimFiles(m);
   return {
     ts: m.ts ?? null,
     user: m.user ?? null,
@@ -201,6 +234,9 @@ function slimMsg(m: Record<string, Json>): Record<string, Json> {
     bot_id: m.bot_id ?? null,
     thread_ts: m.thread_ts ?? null,
     text: typeof m.text === "string" ? m.text : "",
+    // Present only when the message carries attachments, so scripts can reliably
+    // detect files without the key adding noise to every plain-text line.
+    ...(files.length > 0 ? { files } : {}),
   };
 }
 
@@ -554,6 +590,49 @@ function safetyCode(...parts: string[]): string {
   return sha256Hex(parts.join("\n")).slice(0, 4);
 }
 
+// Slack API method → the token scope that grants it, for missing_scope guidance.
+const SCOPE_FOR_METHOD: Record<string, string> = {
+  "reactions.add": "reactions:write",
+  "reactions.remove": "reactions:write",
+  "chat.postMessage": "chat:write",
+  "chat.update": "chat:write",
+  "chat.delete": "chat:write",
+  "conversations.replies": "channels:history (or groups:history)",
+  "conversations.history": "channels:history (or groups:history)",
+};
+
+/** Turn a raw Slack API error into a single clean line of guidance, hiding the
+ *  yargs usage dump / stack trace that a thrown handler would otherwise print.
+ *  Recognizes the common reaction/message failure codes; falls back to the
+ *  original message for anything unmapped. */
+function friendlySlackError(e: unknown): string {
+  const raw = e instanceof Error ? e.message : String(e);
+  const m = raw.match(/Slack error on (\S+): (\w+)/);
+  if (!m) return raw;
+  const [, method, code] = m;
+  switch (code) {
+    case "missing_scope": {
+      const scope = SCOPE_FOR_METHOD[method!] ?? "the required";
+      // Note the token-type gotcha: the CLI uses the USER token (xoxp) by default,
+      // so the scope must be in "User Token Scopes" — adding it only to "Bot Token
+      // Scopes" fixes `--as-bot`/`doctor` but not the default path. Then reinstall.
+      return `Error: token lacks the ${scope} scope (needed for ${method}). Add it to your Slack App's User Token Scopes (or Bot Token Scopes if you use a bot token / --as-bot) — it must be on the token type the CLI actually uses — then reinstall to the workspace.`;
+    }
+    case "invalid_name":
+      return `Error: not a valid emoji shortcode — use the name without colons (e.g. white_check_mark), and make sure it exists in the workspace.`;
+    case "already_reacted":
+      return `Error: you've already added that reaction to the message.`;
+    case "no_reaction":
+      return `Error: that reaction isn't on the message — nothing to remove.`;
+    case "message_not_found":
+      return `Error: no message found at that timestamp in the channel — check the target ts/permalink.`;
+    case "channel_not_found":
+      return `Error: channel not found — check the target.`;
+    default:
+      return raw;
+  }
+}
+
 /** Dry-run gate: print context, print required --code=, exit 1.
  *  Call this when --code is absent or wrong. */
 function requireCode(provided: string | undefined, expected: string, contextLines: string[]): void {
@@ -627,26 +706,73 @@ async function destLabel(token: string, channelId: string, ref: string): Promise
   return name === channelId ? channelId : `${name} (${channelId})`;
 }
 
+/** One-line description of a single thread message for confirm gates:
+ *  "2026-06-11 08:05 @handle: head…". `headLen` bounds the text preview. */
+async function threadMsgLine(token: string, m: Record<string, Json>, headLen = 60): Promise<string> {
+  const author = typeof m.user === "string"
+    ? await userName(token, m.user)
+    : typeof m.username === "string"
+    ? m.username
+    : "?";
+  const head = (typeof m.text === "string" ? m.text : "").split("\n")[0] ?? "";
+  const headShort = head.length > headLen ? `${head.slice(0, headLen)}…` : head;
+  const ts = typeof m.ts === "string" ? m.ts : "";
+  const stamp = ts ? slackTsToIso(ts).slice(0, 16).replace("T", " ") : "";
+  return `${stamp} @${author}${headShort ? `: ${headShort}` : ""}`;
+}
+
 /** One-line thread-parent description for confirm gates: "2026-06-11 08:05 @handle: head…".
- *  Fail-soft: returns the raw ts if the parent cannot be fetched. */
-async function threadParentLine(token: string, channelId: string, threadTs: string): Promise<string> {
-  try {
-    const resp = (await replies(token, channelId, threadTs, 1)) as Record<string, Json>;
-    const msgs = asArray(resp.messages).map(asRecord);
-    const parent = msgs.find((m) => String(m.ts) === threadTs) ?? msgs[0];
-    if (!parent) return threadTs;
-    const author = typeof parent.user === "string"
-      ? await userName(token, parent.user)
-      : typeof parent.username === "string"
-      ? parent.username
-      : "?";
-    const head = (typeof parent.text === "string" ? parent.text : "").split("\n")[0] ?? "";
-    const headShort = head.length > 40 ? `${head.slice(0, 40)}…` : head;
-    const stamp = slackTsToIso(threadTs).slice(0, 16).replace("T", " ");
-    return `${stamp} @${author}${headShort ? `: ${headShort}` : ""}`;
-  } catch {
-    return threadTs;
+ *  Fail-soft: returns the raw ts if the parent cannot be found. */
+async function threadParentLine(token: string, threadTs: string, threadMsgs: Record<string, Json>[]): Promise<string> {
+  const parent = threadMsgs.find((m) => String(m.ts) === threadTs) ?? threadMsgs[0];
+  if (!parent) return threadTs;
+  return threadMsgLine(token, parent, 40);
+}
+
+/** Normalize a message for duplicate comparison: lowercase, collapse whitespace,
+ *  strip <@U…>/<#C…> markup and surrounding punctuation so cosmetic differences
+ *  (a trailing period, an added mention) don't hide a re-post. */
+function normalizeForDup(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/<[@#!][^>]+>/g, " ")
+    .replace(/[^\p{L}\p{N}\s]/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Character-bigram Dice coefficient (0..1) over normalized text — robust to
+ *  minor edits, good at catching near-identical re-posts. Identical strings →1;
+ *  a shared word or two in otherwise different messages stays low. */
+function textSimilarity(a: string, b: string): number {
+  const na = normalizeForDup(a);
+  const nb = normalizeForDup(b);
+  if (!na || !nb) return 0;
+  if (na === nb) return 1;
+  const bigrams = (s: string): Map<string, number> => {
+    const m = new Map<string, number>();
+    for (let i = 0; i < s.length - 1; i++) {
+      const g = s.slice(i, i + 2);
+      m.set(g, (m.get(g) ?? 0) + 1);
+    }
+    return m;
+  };
+  const ba = bigrams(na);
+  const bb = bigrams(nb);
+  if (ba.size === 0 || bb.size === 0) return 0;
+  let overlap = 0;
+  for (const [g, count] of ba) {
+    const other = bb.get(g);
+    if (other) overlap += Math.min(count, other);
   }
+  const total = sumCounts(ba) + sumCounts(bb);
+  return total === 0 ? 0 : (2 * overlap) / total;
+}
+
+function sumCounts(m: Map<string, number>): number {
+  let n = 0;
+  for (const v of m.values()) n += v;
+  return n;
 }
 
 // --- edit ---
@@ -740,6 +866,38 @@ async function cmdDelete(token: string, args: DeleteArgs): Promise<void> {
   console.log(`✓ Deleted (ts: ${ts})`);
 }
 
+// --- react ---
+interface ReactArgs {
+  target: string;
+  emoji: string;
+  remove?: boolean;
+  channelId?: string;
+}
+// Add (or --remove) an emoji reaction. No confirm gate: a reaction is trivial
+// and fully reversible (`--remove`), and the whole point is a lightweight ack
+// that doesn't grow the thread. The emoji is a shortcode without colons
+// (e.g. "eyes", "white_check_mark", "hourglass").
+async function cmdReact(token: string, args: ReactArgs): Promise<void> {
+  const { ref, ts } = splitRefTs(args.target);
+  if (!ts) {
+    console.error("Error: target must embed a message ts (e.g. #chan:2026-05-11T06:01:04.000100 or a Slack permalink URL)");
+    process.exit(2);
+  }
+  const emoji = args.emoji.replace(/^:|:$/g, "");
+
+  let channelId: string;
+  if (args.channelId) channelId = args.channelId;
+  else channelId = await resolveChannel(token, ref);
+
+  if (args.remove) {
+    await reactionRemove(token, channelId, ts, emoji);
+    console.log(`✓ Removed :${emoji}: (ts: ${ts})`);
+  } else {
+    await reactionAdd(token, channelId, ts, emoji);
+    console.log(`✓ Reacted :${emoji}: (ts: ${ts})`);
+  }
+}
+
 // --- send ---
 interface SendArgs {
   target: string;
@@ -796,25 +954,73 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
     ? await encodeMentions(args.mentionToken ?? token, args.message, channelId)
     : args.message;
 
-  // Fetch last 1 message for context hash. Fail-soft: a bot token without
-  // im:history (or channels:history) can still send — only the preview of the
-  // prior message is lost, so default to empty rather than blocking the send.
-  let lastText = "";
-  let lastUser = "?";
+  // Warn-only lint: names written as plain text that map to a known workspace
+  // member but aren't <@USERID>-tagged — they won't be notified. Never blocks;
+  // fail-soft (a missing users:read scope or API error must not stall a send).
   try {
-    const ctx = (await history(token, channelId, 1)) as Record<string, Json>;
-    const lastMsg = asArray(ctx.messages).map(asRecord)
-      .filter((m) => m.subtype === undefined || m.subtype === null)[0];
-    lastText = typeof lastMsg?.text === "string" ? lastMsg.text : "";
-    // Resolve the author's user ID to a display name for the preview; fall back
-    // to the bot username, then the raw ID. userName() is fail-soft.
-    lastUser = typeof lastMsg?.user === "string"
-      ? await userName(token, lastMsg.user)
-      : typeof lastMsg?.username === "string"
-      ? lastMsg.username
-      : "?";
+    for (const u of await findUntaggedMentions(args.mentionToken ?? token, message)) {
+      console.error(`⚠ possible untagged mention: ${u.surface} — @${u.display} won't be notified (did you mean <@${u.userId}>?)`);
+    }
   } catch {
-    // best-effort preview only
+    // best-effort; ignore
+  }
+
+  // Gather context for the confirm gate. For a THREAD reply, pull the thread's
+  // own recent messages so the preview shows what's already been said there —
+  // this is what stops accidental duplicate replies (the channel's last message
+  // is irrelevant when you're deep in a thread). For a top-level send, fall back
+  // to the channel's last message. Fail-soft throughout: a bot token without
+  // history scope can still send; only the preview degrades.
+  let lastText = "";
+  let lastUser = "?";
+  let threadMsgs: Record<string, Json>[] = [];
+  if (threadTs) {
+    try {
+      // Fetch a generous window and preview its tail. conversations.replies is
+      // oldest-first from the parent, so a very long thread's true tail may lie
+      // beyond this window — 100 covers essentially all real threads.
+      const resp = (await replies(token, channelId, threadTs, 100)) as Record<string, Json>;
+      threadMsgs = asArray(resp.messages).map(asRecord);
+      const lastMsg = threadMsgs[threadMsgs.length - 1];
+      // Bind the hash to the thread's most recent message: if someone replies
+      // between preview and confirm, the code invalidates and re-previews.
+      lastText = typeof lastMsg?.text === "string" ? lastMsg.text : "";
+    } catch {
+      // best-effort preview only
+    }
+  } else {
+    try {
+      const ctx = (await history(token, channelId, 1)) as Record<string, Json>;
+      const lastMsg = asArray(ctx.messages).map(asRecord)
+        .filter((m) => m.subtype === undefined || m.subtype === null)[0];
+      lastText = typeof lastMsg?.text === "string" ? lastMsg.text : "";
+      // Resolve the author's user ID to a display name for the preview; fall back
+      // to the bot username, then the raw ID. userName() is fail-soft.
+      lastUser = typeof lastMsg?.user === "string"
+        ? await userName(token, lastMsg.user)
+        : typeof lastMsg?.username === "string"
+        ? lastMsg.username
+        : "?";
+    } catch {
+      // best-effort preview only
+    }
+  }
+
+  // Duplicate guard: if the outgoing message closely matches something already
+  // in the thread, warn (never block). Catches re-posting a reply you already
+  // sent. Threshold is deliberately high so only near-identical text trips it.
+  if (threadTs && threadMsgs.length) {
+    let best = { sim: 0, msg: null as Record<string, Json> | null };
+    for (const m of threadMsgs) {
+      const t = typeof m.text === "string" ? m.text : "";
+      if (!t) continue;
+      const sim = textSimilarity(message, t);
+      if (sim > best.sim) best = { sim, msg: m };
+    }
+    if (best.msg && best.sim >= 0.82) {
+      const pct = Math.round(best.sim * 100);
+      console.error(`⚠ possible duplicate: ${pct}% similar to an existing thread message — ${await threadMsgLine(token, best.msg)}`);
+    }
   }
 
   // Hash covers the destination too — a code minted for one channel/thread
@@ -823,17 +1029,32 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
 
   if (args.code !== code) {
     const dest = await destLabel(token, channelId, ref);
-    const destLine = threadTs
-      ? `  → ${dest} thread of ${await threadParentLine(token, channelId, threadTs)} — THREAD REPLY`
-      : `  → ${dest} — NEW top-level message`;
-    requireCode(args.code, code, [
-      `--- Last message in channel ------------------`,
-      `  ${lastUser}: ${lastText.split("\n")[0]?.slice(0, 100) ?? "(empty)"}`,
-      `--- Sending ----------------------------------`,
-      destLine,
-      `  Message: ${message}`,
-      `--------------------------------────────────`,
-    ]);
+    if (threadTs) {
+      const parentLine = await threadParentLine(token, threadTs, threadMsgs);
+      // Preview the tail of the thread (up to 3 most recent messages) so the
+      // sender can see what's already been said and avoid repeating it.
+      const recent = threadMsgs.slice(-3);
+      const recentLines = recent.length
+        ? await Promise.all(recent.map(async (m) => `  ${await threadMsgLine(token, m)}`))
+        : ["  (thread context unavailable)"];
+      requireCode(args.code, code, [
+        `--- Recent messages in thread ----------------`,
+        ...recentLines,
+        `--- Sending ----------------------------------`,
+        `  → ${dest} thread of ${parentLine} — THREAD REPLY`,
+        `  Message: ${message}`,
+        `--------------------------------────────────`,
+      ]);
+    } else {
+      requireCode(args.code, code, [
+        `--- Last message in channel ------------------`,
+        `  ${lastUser}: ${lastText.split("\n")[0]?.slice(0, 100) ?? "(empty)"}`,
+        `--- Sending ----------------------------------`,
+        `  → ${dest} — NEW top-level message`,
+        `  Message: ${message}`,
+        `--------------------------------────────────`,
+      ]);
+    }
   }
   const ts = await slackSend(token, channelId, message, threadTs, args.broadcast);
   let permalink = "";
@@ -988,10 +1209,6 @@ async function cmdUpload(token: string, args: UploadArgs): Promise<void> {
   else if (args.userId) channelId = await openDm(token, args.userId);
   else channelId = await resolveChannel(token, ref);
 
-  function fmtSize(n: number): string {
-    return n < 1024 ? `${n} B` : n < 1048576 ? `${(n / 1024).toFixed(1)} KB` : `${(n / 1048576).toFixed(1)} MB`;
-  }
-
   const isBatch = args.filePaths.length > 1;
   const files = args.filePaths.map((fp) => {
     const filename = basename(fp);
@@ -1033,6 +1250,42 @@ async function cmdUpload(token: string, args: UploadArgs): Promise<void> {
   }
 }
 
+// --- download <ref> [dest] — fetch an attachment's bytes to disk (read-only) ---
+// ref: a file ID (F…) or a Slack file permalink (…/files/<UID>/<FID>/<name>).
+function parseFileId(ref: string): string | undefined {
+  if (/^F[A-Z0-9]+$/i.test(ref)) return ref;
+  return ref.match(/\/files\/[A-Za-z0-9]+\/(F[A-Za-z0-9]+)/)?.[1];
+}
+
+async function cmdDownload(token: string, cookie: string | undefined, ref: string, dest?: string): Promise<void> {
+  const fileId = parseFileId(ref);
+  if (!fileId) {
+    throw new Error(
+      `Not a file ID or file permalink: ${ref}\n` +
+      `Expected F… or https://<ws>.slack.com/files/<UID>/<FID>/<name>`,
+    );
+  }
+  const info = asRecord((await filesInfo(token, fileId, cookie)) as Json);
+  const f = asRecord(info.file);
+  const name = typeof f.name === "string" ? f.name : typeof f.title === "string" ? f.title : fileId;
+  const url = typeof f.url_private_download === "string" ? f.url_private_download
+    : typeof f.url_private === "string" ? f.url_private : "";
+  if (!url) throw new Error(`files.info returned no download URL for ${fileId}`);
+
+  const headers: Record<string, string> = { Authorization: `Bearer ${token}` };
+  if (cookie) headers.Cookie = `d=${cookie}`;
+  const res = await fetch(url, { headers });
+  if (!res.ok) throw new Error(`Download failed: HTTP ${res.status} ${res.statusText}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+
+  const { statSync, existsSync } = await import("node:fs");
+  const { basename } = await import("node:path");
+  let outPath = dest ?? name;
+  if (dest && existsSync(dest) && statSync(dest).isDirectory()) outPath = join(dest, basename(name));
+  writeFileSync(outPath, buf);
+  console.log(`✓ Downloaded ${name} (${fmtSize(buf.length)}) → ${outPath}`);
+}
+
 // --- dispatch ---
 
 async function main(): Promise<void> {
@@ -1369,7 +1622,7 @@ async function main(): Promise<void> {
         try {
           await cmdSend(sendToken, args);
         } catch (e: unknown) {
-          console.error(e instanceof Error ? e.message : String(e));
+          console.error(friendlySlackError(e));
           process.exit(1);
         }
       },
@@ -1472,6 +1725,28 @@ async function main(): Promise<void> {
         await cmdDelete(tok(argv as W), args);
       },
     )
+    .command(
+      "react <target> <emoji>",
+      "Add (or --remove) an emoji reaction — a lightweight ack that doesn't grow the thread",
+      (y) => y
+        .positional("target", { type: "string", demandOption: true, describe: "#chan:ts, @user:ts, or permalink" })
+        .positional("emoji", { type: "string", demandOption: true, describe: "Emoji shortcode without colons (e.g. eyes, white_check_mark, hourglass)" })
+        .option("remove", { type: "boolean", default: false, describe: "Remove the reaction instead of adding it" })
+        .option("channel-id", { type: "string", describe: "Raw channel ID" }),
+      async (argv) => {
+        const args: ReactArgs = { target: argv.target!, emoji: argv.emoji! };
+        if (argv.remove) args.remove = true;
+        if (argv["channel-id"]) args.channelId = argv["channel-id"];
+        // Print a clean one-line error instead of yargs' usage dump + stack when
+        // the reaction fails at runtime (missing_scope, invalid_name, etc.).
+        try {
+          await cmdReact(tok(argv as W), args);
+        } catch (e: unknown) {
+          console.error(friendlySlackError(e));
+          process.exit(1);
+        }
+      },
+    )
     .command(
       "upload <target> <file..>",
       "Upload one or more files to a channel or DM",
@@ -1493,6 +1768,16 @@ async function main(): Promise<void> {
         await cmdUpload(tok(argv as W), args);
       },
     )
+    .command(
+      "download <ref> [dest]",
+      "Download a file attachment (by file ID or file permalink) to disk",
+      (y) => y
+        .positional("ref", { type: "string", demandOption: true, describe: "File ID (F…) or Slack file permalink" })
+        .positional("dest", { type: "string", describe: "Output path or directory (default: ./<filename>)" }),
+      async (argv) => {
+        await cmdDownload(tok(argv as W), ck(argv as W), argv.ref!, argv.dest);
+      },
+    )
     .command(
       "dump",
       "Bulk export channel history as markdown",

package/ts/format.ts

@@ -93,6 +93,115 @@ export async function encodeMentions(
   });
 }
 
+// --- untagged-mention lint (warn-only) -------------------------------------
+// Flags names written as plain text that map to a known workspace member but
+// carry no <@USERID> tag in the same message — the footgun where "松田さん"
+// reads fine to a human but never actually notifies 松田. Never blocks a send.
+
+// Person-reference cues. Honorific *suffixes* follow a name (JP + ZH); greeting
+// *prefixes* precede one (EN, handled by regex below). Extend freely.
+const HONORIFIC_SUFFIXES = [
+  "さん", "さま", "様", "君", "くん", "ちゃん", "氏", "先生", "先輩", "殿",  // JP
+  "老师", "老師", "兄", "姐", "哥", "姐妹",                                  // ZH
+];
+
+const NAME_CHARS = "\\p{Script=Han}\\p{Script=Hiragana}\\p{Script=Katakana}A-Za-z0-9";
+
+function isCjk(s: string): boolean {
+  return /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/u.test(s);
+}
+
+type PersonRef = { ref: string; honorific: string };
+
+/** Extract candidate person-references from plain text. CJK matches by honorific
+ *  suffix; EN by "Dear/Hi/Hello/Hey <Name>" and a leading "<Name>," salutation.
+ *  Over-capture on the CJK side is harmless: a ref matching no member is dropped,
+ *  and the warning's surface is rebuilt from the matched member name. */
+function extractPersonRefs(text: string): PersonRef[] {
+  const refs: PersonRef[] = [];
+  const honRe = new RegExp(`([${NAME_CHARS}]{1,12})(${HONORIFIC_SUFFIXES.join("|")})`, "gu");
+  for (const m of text.matchAll(honRe)) refs.push({ ref: m[1]!, honorific: m[2]! });
+  for (const m of text.matchAll(/\b(?:dear|hi|hello|hey)\b[ \t]+([A-Z][A-Za-z'’-]{1,20})/gi)) {
+    refs.push({ ref: m[1]!, honorific: "" });
+  }
+  for (const m of text.matchAll(/(?:^|\n)[ \t]*([A-Z][A-Za-z'’-]{1,20}),/g)) {
+    refs.push({ ref: m[1]!, honorific: "" });
+  }
+  return refs;
+}
+
+/** Normalized name forms of a member (name / real_name / display_name plus their
+ *  whitespace-split parts), lowercased+stripped, length ≥ 2. */
+function nameFormsOf(u: Record<string, Json>): string[] {
+  const profile = asRecord(u.profile);
+  const forms = new Set<string>();
+  for (const v of [u.name, u.real_name, profile.display_name, profile.real_name]) {
+    if (typeof v !== "string" || !v) continue;
+    for (const piece of [v, ...v.split(/\s+/)]) {
+      const n = normHandle(piece);
+      if (n.length >= 2) forms.add(n);
+    }
+  }
+  return [...forms];
+}
+
+/** The member name-form that a ref matches, or undefined. CJK allows substring
+ *  either direction (tolerates over-capture / compound names); Latin requires an
+ *  exact form match to avoid "Ai" ⊂ "Aiden" style false positives. */
+function matchMemberForm(ref: string, forms: string[]): string | undefined {
+  const nr = normHandle(ref);
+  if (nr.length < 2) return undefined;
+  // Exact first so the surface rebuilds to the tightest name (e.g. an
+  // over-captured "ください松田" still reports "松田", not the whole run).
+  for (const f of forms) if (nr === f) return f;
+  if (isCjk(ref)) {
+    for (const f of forms) if (nr.includes(f) || f.includes(nr)) return f;
+  }
+  return undefined;
+}
+
+function displayNameOf(u: Record<string, Json>): string {
+  const profile = asRecord(u.profile);
+  const names = [profile.display_name, u.real_name, u.name].filter(
+    (v): v is string => typeof v === "string" && v !== "",
+  );
+  return names[0] ?? String(u.id ?? "?");
+}
+
+export type UntaggedMention = { surface: string; display: string; userId: string };
+
+/** Warn-only lint: person-references in `text` that resolve to a workspace
+ *  member but carry no <@USERID> tag. Returns [] cheaply (no users.list fetch)
+ *  when the text has no person-reference cue. */
+export async function findUntaggedMentions(token: string, text: string): Promise<UntaggedMention[]> {
+  const refs = extractPersonRefs(text);
+  if (refs.length === 0) return [];
+
+  const taggedIds = new Set<string>();
+  for (const m of text.matchAll(/<@([A-Z0-9]+)(?:\|[^>]*)?>/g)) taggedIds.add(m[1]!);
+
+  const wsResp = (await listUsers(token)) as { members?: Json[] };
+  const pool = (wsResp.members ?? [])
+    .map(asRecord)
+    .filter((u) => u.deleted !== true && u.is_bot !== true && u.id !== "USLACKBOT")
+    .map((u) => ({ id: typeof u.id === "string" ? u.id : "", forms: nameFormsOf(u), display: displayNameOf(u) }))
+    .filter((p) => p.id !== "");
+
+  const out: UntaggedMention[] = [];
+  const seen = new Set<string>();
+  for (const { ref, honorific } of refs) {
+    for (const p of pool) {
+      const form = matchMemberForm(ref, p.forms);
+      if (!form) continue;
+      if (taggedIds.has(p.id) || seen.has(p.id)) break;
+      seen.add(p.id);
+      out.push({ surface: isCjk(ref) ? `${form}${honorific}` : ref, display: p.display, userId: p.id });
+      break;
+    }
+  }
+  return out;
+}
+
 export async function resolveMentions(
   token: string,
   text: string,

package/ts/slack.ts

@@ -181,6 +181,13 @@ export async function replies(
   return get(token, "conversations.replies", { channel, ts, limit: String(limit) });
 }
 
+// Metadata for a single uploaded file (files.info). Carries url_private_download,
+// which requires an Authorization: Bearer token (+ xoxd cookie for session tokens)
+// to actually fetch the bytes.
+export async function filesInfo(token: string, fileId: string, cookie?: string): Promise<Json> {
+  return get(token, "files.info", { file: fileId }, cookie);
+}
+
 export async function searchPage(
   token: string,
   query: string,
@@ -314,6 +321,28 @@ export async function deleteMessage(
   await post(token, "chat.delete", { channel, ts });
 }
 
+// Add or remove an emoji reaction on a message. `name` is the emoji shortcode
+// without colons (e.g. "eyes", "white_check_mark"). Slack's reactions.add
+// returns already_reacted when the reaction exists; reactions.remove returns
+// no_reaction when it doesn't — both surface to the caller as API errors.
+export async function reactionAdd(
+  token: string,
+  channel: string,
+  ts: string,
+  name: string,
+): Promise<void> {
+  await post(token, "reactions.add", { channel, timestamp: ts, name });
+}
+
+export async function reactionRemove(
+  token: string,
+  channel: string,
+  ts: string,
+  name: string,
+): Promise<void> {
+  await post(token, "reactions.remove", { channel, timestamp: ts, name });
+}
+
 // Create a public (or private) channel via conversations.create. Slack
 // lowercases the name and rejects spaces/most punctuation; the raw API error
 // (e.g. name_taken, invalid_name_specials) surfaces to the caller. Returns the