slack-term 1.28.1 → 1.30.0

package/package.json

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

package/ts/cli.ts

@@ -85,6 +85,7 @@ import {
   todoDoctor,
   todoFlag,
   userHandleCached,
+  userTzCached,
   todoSet,
   withRateLimitRetry,
   DOCTOR_DEFAULT_LIMIT,
@@ -95,6 +96,7 @@ import {
 } from "./todo.ts";
 import { setCacheEnabled } from "./cache.ts";
 import { dayLabel, encodeMentions, encodeMentionsDetailed, findUntaggedMentions, formatYmdHm, mentionWarnings, resolveDateMarkup, resolveMentions, type MentionEncodeResult } from "./format.ts";
+import { quietHoursNotice } from "./quietHours.ts";
 
 function loadDotenv(path: string): void {
   if (!existsSync(path)) return;
@@ -891,8 +893,35 @@ function friendlySlackError(e: unknown): string {
 
 /** 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 {
+/** The recipient's timezone for the quiet-hours label — DM only.
+ *
+ *  A channel has many recipients in potentially many zones, and resolving every
+ *  member would cost a lookup per person to answer a question that has no single
+ *  answer. DMs are also where a 3am notification actually lands on someone's
+ *  phone, so this is where the check earns its keep.
+ *
+ *  Returns null (= "unknown", label says so) for channels, for a self-DM, and
+ *  for anyone Slack has no timezone for. */
+async function recipientTzFor(token: string, channelId: string, cookie?: string): Promise<string | null> {
+  if (!channelId.startsWith("D")) return null;
+  try {
+    const other = await imCounterpart(token, channelId, cookie);
+    if (!other) return null;
+    return await userTzCached(token, other, userInfo, cookie);
+  } catch {
+    return null;
+  }
+}
+
+function requireCode(provided: string | undefined, expected: string, contextLines: string[], recipientTz?: string | null): void {
+  // The clock goes to stdout with the rest of the preview, not to stderr with
+  // the code. The preview is what you are asked to LOOK at before committing,
+  // and "what time is it where they are" is part of that picture — a caller
+  // doing `send ... 2>/dev/null` to read the preview would otherwise drop the
+  // one line added to stop a 01:00 send.
   for (const line of contextLines) console.log(line);
+  const clock = quietHoursNotice(new Date(), recipientTz);
+  if (clock) console.log(clock);
   if (provided !== undefined) {
     console.error(`Code mismatch (got ${provided}, expected ${expected})`);
   }
@@ -1490,6 +1519,9 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
   // profile / SLACK_TOKEN / --as-bot switch between preview and confirm
   // re-previews instead). Empty on lookup failure, same fail-soft as lastText.
   const self = await getSelf();
+  // Resolved before the gate so the clock can name the recipient's zone. DM
+  // only; null means "unknown" and the label says so rather than guessing.
+  const recipientTz = await recipientTzFor(token, channelId, cookie);
   const code = safetyCode(channelId, threadTs ?? "", lastText, message, self?.userId ?? "");
 
   if (args.code !== code) {
@@ -1512,7 +1544,7 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
         `  → ${dest} thread of ${parentLine} — THREAD REPLY`,
         `  Message: ${message}`,
         `--------------------------------────────────`,
-      ]);
+      ], recipientTz);
     } else {
       requireCode(args.code, code, [
         `--- Last message in channel ------------------`,
@@ -1523,7 +1555,7 @@ async function cmdSend(token: string, args: SendArgs): Promise<void> {
         `  → ${dest} — NEW top-level message`,
         `  Message: ${message}`,
         `--------------------------------────────────`,
-      ]);
+      ], recipientTz);
     }
   }
   const ts = await slackSend(token, channelId, message, threadTs, args.broadcast, cookie);
@@ -2027,6 +2059,9 @@ async function cmdAsk(token: string, args: AskArgs): Promise<void> {
   // satisfies by calling twice. The hash binds destination, thread, the exact
   // posted body (question AND choices) and the asking identity.
   const self = await getSelf();
+  // Resolved before the gate so the clock can name the recipient's zone. DM
+  // only; null means "unknown" and the label says so rather than guessing.
+  const recipientTz = await recipientTzFor(token, channelId, cookie);
   const code = safetyCode(channelId, threadTs ?? "", lastText, message, self?.userId ?? "");
   if (args.code !== code) {
     const dest = await destLabel(token, channelId, ref, cookie);
@@ -2048,7 +2083,7 @@ async function cmdAsk(token: string, args: AskArgs): Promise<void> {
       `  Answerable by: ${audienceLabel}`,
       `  Via:      ${threadOnly ? "reactions or thread replies" : "reactions or replies in this DM"}`,
       `--------------------------------────────────`,
-    ]);
+    ], recipientTz);
   }
 
   // `plain`: with blocks attached Slack rewrites the stored text (newlines to
@@ -2345,6 +2380,9 @@ async function cmdPoll(token: string, args: PollArgs): Promise<void> {
   }
 
   const self = await getSelf();
+  // Resolved before the gate so the clock can name the recipient's zone. DM
+  // only; null means "unknown" and the label says so rather than guessing.
+  const recipientTz = await recipientTzFor(token, channelId, cookie);
   const code = safetyCode(channelId, threadTs ?? "", lastText, message, self?.userId ?? "");
   if (args.code !== code) {
     const dest = await destLabel(token, channelId, ref, cookie);
@@ -2361,7 +2399,7 @@ async function cmdPoll(token: string, args: PollArgs): Promise<void> {
       // Said out loud at the gate: this is the surprising half of the command.
       `  Note:     あなた自身の票は数えません (ピルはあなたが付けた種なので区別できません)`,
       `--------------------------------────────────`,
-    ]);
+    ], recipientTz);
   }
 
   // `plain`: no blocks, or Slack rewrites the stored text and the ballot

package/ts/quietHours.ts

@@ -0,0 +1,81 @@
+/** Quiet hours in the recipients' timezone: sending here makes a human's phone
+ *  buzz while they're asleep. Default JST because this workspace is in Japan;
+ *  override with SLACK_QUIET_TZ / SLACK_QUIET_START / SLACK_QUIET_END.
+ *
+ *  WHY this lives in the confirm gate rather than in a doc: an agent driving
+ *  this CLI has no reason to look at a clock — the moment work finishes IS the
+ *  moment it sends, and in a long session it doesn't notice the date rolled
+ *  over. A rule that must be remembered gets forgotten; a line printed on the
+ *  path every send already takes does not. (Real incident 2026-08-26: messages
+ *  sent to an external partner at 00:44 and 01:12 JST.)
+ *
+ *  WHOSE clock: the recipient's, when we can learn it — "is it the middle of
+ *  the night" is a fact about the person whose phone buzzes, not about the
+ *  sender. `recipientTz` carries that when the caller could resolve it.
+ *
+ *  When it is UNKNOWN we still judge, using the sender's zone, and say plainly
+ *  that we did. That is the whole design decision here, and the tempting
+ *  alternatives are both worse:
+ *
+ *    - Silently falling back to the default zone LOOKS clean and reads as if
+ *      we knew the recipient's time. It lies.
+ *    - Declining to judge at all is honest, but it hands the decision back to
+ *      an agent that has no reason to look at a clock — which is the exact
+ *      failure this exists to prevent. Measured against the real incident,
+ *      that option is the ONLY one of the three that stays silent at 00:44.
+ *
+ *  So: warn, and label the basis. Unknown is not the rare case — Slack Connect
+ *  counterparts have no `tz` field at all (measured 2026-08-26 on every
+ *  external user in this workspace, including the person the 00:44 message
+ *  actually went to). Falling silent there would reinstate the incident.
+ *
+ *  Deliberately a WARNING, not a block: pager-duty style P1 outage notices
+ *  legitimately go out at 3am, and this CLI cannot tell those apart. Blocking
+ *  would train people to bypass the gate entirely. */
+export function quietHoursNotice(now: Date = new Date(), recipientTz?: string | null): string | null {
+  const fallbackTz = process.env.SLACK_QUIET_TZ ?? "Asia/Tokyo";
+  // An unusable recipient zone is treated as unknown, not as a reason to fail:
+  // the sender's zone still gives a defensible answer, and the label says so.
+  const known = !!recipientTz && isUsableTz(recipientTz);
+  const tz = known ? recipientTz! : fallbackTz;
+  const start = Number(process.env.SLACK_QUIET_START ?? 23); // inclusive
+  const end = Number(process.env.SLACK_QUIET_END ?? 8); // exclusive
+  let hour: number;
+  let stamp: string;
+  try {
+    const fmt = new Intl.DateTimeFormat("en-GB", {
+      timeZone: tz,
+      hour12: false,
+      weekday: "short",
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+    });
+    stamp = fmt.format(now);
+    hour = Number(
+      fmt.formatToParts(now).find((p) => p.type === "hour")?.value ?? "12",
+    );
+  } catch {
+    return null; // bad TZ override — never let the clock break sending
+  }
+  const quiet = start > end ? hour >= start || hour < end : hour >= start && hour < end;
+  // Name the basis, always. A reader who cannot tell whose clock this is cannot
+  // judge how much to trust it.
+  const basis = known ? `${tz}, recipient` : `${tz}, sender — recipient's timezone unknown`;
+  const label = `🕐 ${stamp} (${basis})`;
+  if (!quiet) return label;
+  const caveat = known ? "" : " Their local time may differ.";
+  return `${label}\n⚠ QUIET HOURS (${start}:00-${end}:00) — this will buzz a phone.${caveat} Send only for a production incident; otherwise hold it until morning.`;
+}
+
+/** Does Intl accept this zone? A bad value must degrade to "unknown", never throw. */
+function isUsableTz(tz: string): boolean {
+  try {
+    new Intl.DateTimeFormat("en-GB", { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/ts/todo.ts

@@ -299,6 +299,52 @@ export async function userHandleCached(
   return handle;
 }
 
+/** The recipient's IANA timezone, or null when Slack does not know it.
+ *
+ *  Cached on the same 1h TTL as handles, so a send costs no extra API call in
+ *  practice. `users:read` failures are swallowed: a missing scope must degrade
+ *  the quiet-hours label, never block sending.
+ *
+ *  NOTE the shape check. Slack Connect counterparts have NO `tz` KEY at all —
+ *  not `tz: null`, the key is simply absent (measured 2026-08-26 on every
+ *  external user in this workspace). So `=== null` would sail straight past it;
+ *  only a truthy-string test is correct here. */
+export async function userTzCached(
+  token: string,
+  userId: string,
+  lookup: (token: string, userId: string, cookie?: string) => Promise<unknown>,
+  cookie?: string,
+): Promise<string | null> {
+  const scope = await cacheScope(token, cookie);
+  const hit = cacheGet("users", scope, `tz:${userId}`);
+  if (hit) return hit === "?" ? null : hit;
+  let tz: string | null = null;
+  try {
+    const resp = (await withRateLimitRetry("users.info", () => lookup(token, userId, cookie))) as
+      { user?: { tz?: unknown; is_bot?: unknown } };
+    // A bot reports America/Los_Angeles (Slack's own default) and has no phone
+    // to buzz, so its "timezone" is a false signal — treat it as unknown rather
+    // than warn about the middle of the night in California. Measured on this
+    // workspace's bot user, and the same bogus value shows up in users.list.
+    if (resp?.user?.is_bot === true) return cacheThen(scope, userId, null);
+    const raw = resp?.user?.tz;
+    tz = typeof raw === "string" && raw ? raw : null;
+  } catch {
+    // No users:read, rate limit exhausted, network — all mean "unknown", and
+    // unknown is a state the caller already handles. Never fail the send.
+    return null;
+  }
+  return cacheThen(scope, userId, tz);
+}
+
+/** Persist and return. "?" records a definite "Slack has no timezone for this
+ *  person", so we do not re-ask every send for the external users and bots that
+ *  will never have a usable one. */
+function cacheThen(scope: string, userId: string, tz: string | null): string | null {
+  cacheSet("users", scope, `tz:${userId}`, tz ?? "?");
+  return tz;
+}
+
 // ── set / flag ────────────────────────────────────────────────────────────
 
 export type SetResult = {