slack-term 1.19.0 → 1.20.0

package/package.json

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

package/ts/cli.ts

@@ -24,6 +24,7 @@ import {
   updateDraft,
   editMessage,
   deleteMessage,
+  filesInfo,
   history,
   listConversations,
   listDrafts,
@@ -48,7 +49,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 +187,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 +232,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 } : {}),
   };
 }
 
@@ -796,6 +830,17 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
     ? await encodeMentions(args.mentionToken ?? token, args.message, channelId)
     : args.message;
 
+  // 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 {
+    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; ignore
+  }
+
   // 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.
@@ -988,10 +1033,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 +1074,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> {
@@ -1493,6 +1570,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

@@ -3,11 +3,13 @@
 import { listConversationMembers, listUsers, userInfo, userName, type Json } from "./slack.ts";
 
 /** Match an `@handle` token at a word boundary, capturing the handle.
- *  - The negative lookbehind keeps `@` inside emails (`a@b.com`) from matching.
+ *  - The negative lookbehind keeps `@` inside emails (`a@b.com`) from matching,
+ *    and the `<` keeps already-encoded mentions (`<@U0123>`) from being picked up
+ *    as a handle named after the user ID (Slack resolves those natively).
  *  - Each `.` must be followed by more handle chars, so a trailing sentence dot
  *    (`thanks @taku.`) is left out of the capture. */
 function mentionRe(): RegExp {
-  return /(?<![A-Za-z0-9._@-])@([A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*)/g;
+  return /(?<![A-Za-z0-9._@<-])@([A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*)/g;
 }
 
 /** Lowercase + strip hyphens/underscores/whitespace for loose handle matching. */
@@ -91,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,