pi-quiver 4.5.0 → 5.1.0

package/lib/slack-cache.ts

@@ -0,0 +1,537 @@
+/**
+ * Name->ID cache for the slack extension: one JSON file per Slack workspace
+ * (keyed by team ID), holding channel and user name->ID maps. Sits on top of
+ * `lib/slack-core.ts`'s ApiCall/SlackError/SlackConfig - stays pi-free like
+ * its sibling core modules.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import type { ApiCall, SlackConfig, UnresolvedMention } from "./slack-core.ts";
+import { SlackError } from "./slack-core.ts";
+
+export interface UserEntry {
+	id: string;
+	display_name: string;
+	real_name: string;
+	email?: string;
+}
+
+export interface SlackCacheFile {
+	team_id: string;
+	channels: Record<string, string>;
+	users: Record<string, UserEntry>;
+	refreshed_at: string;
+	/** Set only by refreshCache's full replacement; presence means this file once held a complete
+	 * workspace listing, which is the only state where an alias match may be trusted from cache. */
+	snapshot_at?: string;
+}
+
+export interface CacheCtx {
+	apiCall: ApiCall;
+	token: string;
+	filePath: string;
+	signal?: AbortSignal;
+}
+
+const RAW_CHANNEL_ID = /^[CDG][A-Z0-9]{5,}$/;
+const RAW_USER_ID = /^[UW][A-Z0-9]{5,}$/;
+
+/** Hard cap on cursor-following pagination loops - a runaway/misbehaving API must fail loudly, never spin or write a partial cache. */
+export const MAX_LIST_PAGES = 100;
+
+/** Same per-OS convention as `lib/doc-to-md-core.ts`'s `cacheDir`, defined locally per spec. */
+export function userCacheDir(platform: NodeJS.Platform, env: Record<string, string | undefined>, home: string): string {
+	if (platform === "win32") return join(env.LOCALAPPDATA ?? join(home, "AppData", "Local"), "pi-quiver");
+	if (platform === "darwin") return join(home, "Library", "Caches", "pi-quiver");
+	return join(env.XDG_CACHE_HOME ?? join(home, ".cache"), "pi-quiver");
+}
+
+export function cacheFilePath(
+	cfg: SlackConfig,
+	repoRoot: string,
+	teamId: string,
+	dirs?: { platform: NodeJS.Platform; env: Record<string, string | undefined>; home: string },
+): string {
+	if (cfg.cachePath) {
+		return isAbsolute(cfg.cachePath) ? cfg.cachePath : join(repoRoot, cfg.cachePath);
+	}
+	const dir = dirs
+		? userCacheDir(dirs.platform, dirs.env, dirs.home)
+		: userCacheDir(process.platform, process.env, process.env.HOME ?? "");
+	return join(dir, `slack-${teamId}.json`);
+}
+
+const teamIdCache = new Map<string, string>();
+
+export async function teamIdFor(token: string, apiCall: ApiCall, signal?: AbortSignal): Promise<string> {
+	const cached = teamIdCache.get(token);
+	if (cached !== undefined) return cached;
+	const data = await apiCall("auth.test", token, {}, { retry: false, signal });
+	const teamId = data.team_id as string;
+	teamIdCache.set(token, teamId);
+	return teamId;
+}
+
+export function assertSameTeam(a: string | undefined, b: string | undefined): void {
+	if (a !== undefined && b !== undefined && a !== b) {
+		throw new SlackError("team_mismatch", `User and bot tokens belong to different workspaces (${a} vs ${b}).`);
+	}
+}
+
+function readCacheFile(filePath: string): SlackCacheFile | undefined {
+	try {
+		return JSON.parse(readFileSync(filePath, "utf8")) as SlackCacheFile;
+	} catch {
+		return undefined;
+	}
+}
+
+function emptyCache(teamId: string): SlackCacheFile {
+	return { team_id: teamId, channels: {}, users: {}, refreshed_at: new Date().toISOString() };
+}
+
+function atomicWrite(filePath: string, data: SlackCacheFile): void {
+	mkdirSync(dirname(filePath), { recursive: true });
+	const tmpPath = `${filePath}.tmp.${process.pid}`;
+	writeFileSync(tmpPath, JSON.stringify(data, null, 2));
+	renameSync(tmpPath, filePath);
+}
+
+function mergeAndWrite(filePath: string, teamId: string, patch: (base: SlackCacheFile) => void): void {
+	const base = existsSync(filePath) ? (readCacheFile(filePath) ?? emptyCache(teamId)) : emptyCache(teamId);
+	patch(base);
+	base.refreshed_at = new Date().toISOString();
+	atomicWrite(filePath, base);
+}
+
+function stripPrefix(input: string): string {
+	return input.startsWith("#") || input.startsWith("@") ? input.slice(1) : input;
+}
+
+function toUserEntry(u: SlackUser): UserEntry {
+	const email = u.profile?.email;
+	return {
+		id: u.id,
+		display_name: u.profile?.display_name ?? "",
+		real_name: u.profile?.real_name ?? u.real_name ?? "",
+		...(email ? { email } : {}),
+	};
+}
+
+export async function resolveChannel(input: string, ctx: CacheCtx): Promise<string> {
+	if (RAW_CHANNEL_ID.test(input)) return input;
+	if (input.startsWith("@")) {
+		throw new SlackError(
+			"invalid_channel",
+			`"${input}" looks like a user name, which is not accepted in a channel position (opening a DM is out of scope).`,
+		);
+	}
+	const name = stripPrefix(input);
+
+	const cached = readCacheFile(ctx.filePath);
+	const hit = cached?.channels[name];
+	if (hit !== undefined) return hit;
+
+	let cursor = "";
+	for (let page = 1; ; page++) {
+		if (page > MAX_LIST_PAGES) {
+			throw new SlackError(
+				"pagination_overflow",
+				`resolveChannel: conversations.list did not terminate within ${MAX_LIST_PAGES} pages.`,
+			);
+		}
+		const data = await ctx.apiCall(
+			"conversations.list",
+			ctx.token,
+			{ limit: 1000, types: "public_channel,private_channel", ...(cursor ? { cursor } : {}) },
+			{ retry: false, signal: ctx.signal },
+		);
+		const channels = (data.channels as { id: string; name: string }[]) ?? [];
+		const match = channels.find((c) => c.name === name);
+		if (match) {
+			mergeAndWrite(ctx.filePath, cached?.team_id ?? (await teamIdFor(ctx.token, ctx.apiCall, ctx.signal)), (base) => {
+				base.channels[name] = match.id;
+			});
+			return match.id;
+		}
+		const meta = data.response_metadata as { next_cursor?: string } | undefined;
+		const nextCursor = meta?.next_cursor ?? "";
+		// Slack can echo the same cursor repeatedly under throttling - treat a repeated non-empty
+		// cursor as exhaustion rather than spinning until MAX_LIST_PAGES.
+		if (nextCursor !== "" && nextCursor === cursor) break;
+		cursor = nextCursor;
+		if (!cursor) break;
+	}
+
+	throw new SlackError("name_not_found", `No channel named "${name}" was found in the workspace.`);
+}
+
+interface SlackUser {
+	id: string;
+	name: string;
+	profile?: { display_name?: string; real_name?: string; email?: string };
+	real_name?: string;
+}
+
+export async function resolveUser(input: string, ctx: CacheCtx): Promise<string> {
+	if (RAW_USER_ID.test(input)) return input;
+	if (input.startsWith("#")) {
+		throw new SlackError(
+			"invalid_user",
+			`"${input}" looks like a channel name, which is not accepted in a user position.`,
+		);
+	}
+	const name = stripPrefix(input);
+
+	const cached = readCacheFile(ctx.filePath);
+	if (cached) {
+		const byUsername = cached.users[name];
+		if (byUsername) return byUsername.id;
+
+		const displayMatches = Object.values(cached.users).filter((u) => u.display_name === name);
+		if (displayMatches.length === 1) return displayMatches[0].id;
+		if (displayMatches.length > 1) {
+			throw new SlackError(
+				"ambiguous_user",
+				`Multiple users have display name "${name}": ${displayMatches.map((u) => u.id).join(", ")}.`,
+			);
+		}
+
+		const realMatches = Object.values(cached.users).filter((u) => u.real_name === name);
+		if (realMatches.length === 1) return realMatches[0].id;
+		if (realMatches.length > 1) {
+			throw new SlackError(
+				"ambiguous_user",
+				`Multiple users have real name "${name}": ${realMatches.map((u) => u.id).join(", ")}.`,
+			);
+		}
+	}
+
+	let cursor = "";
+	const displayCandidates: SlackUser[] = [];
+	const realCandidates: SlackUser[] = [];
+	for (let page = 1; ; page++) {
+		if (page > MAX_LIST_PAGES) {
+			throw new SlackError(
+				"pagination_overflow",
+				`resolveUser: users.list did not terminate within ${MAX_LIST_PAGES} pages.`,
+			);
+		}
+		const data = await ctx.apiCall(
+			"users.list",
+			ctx.token,
+			{ limit: 1000, ...(cursor ? { cursor } : {}) },
+			{ retry: false, signal: ctx.signal },
+		);
+		const members = (data.members as SlackUser[]) ?? [];
+		for (const u of members) {
+			if (u.name === name) {
+				mergeAndWrite(ctx.filePath, cached?.team_id ?? (await teamIdFor(ctx.token, ctx.apiCall, ctx.signal)), (base) => {
+					base.users[name] = toUserEntry(u);
+				});
+				return u.id;
+			}
+			if (u.profile?.display_name === name) displayCandidates.push(u);
+			if ((u.profile?.real_name ?? u.real_name) === name) realCandidates.push(u);
+		}
+		const meta = data.response_metadata as { next_cursor?: string } | undefined;
+		const nextCursor = meta?.next_cursor ?? "";
+		// Slack can echo the same cursor repeatedly under throttling - treat a repeated non-empty
+		// cursor as exhaustion rather than spinning until MAX_LIST_PAGES.
+		if (nextCursor !== "" && nextCursor === cursor) break;
+		cursor = nextCursor;
+		if (!cursor) break;
+	}
+
+	if (displayCandidates.length === 1) {
+		const u = displayCandidates[0];
+		mergeAndWrite(ctx.filePath, cached?.team_id ?? (await teamIdFor(ctx.token, ctx.apiCall, ctx.signal)), (base) => {
+			base.users[u.name] = toUserEntry(u);
+		});
+		return u.id;
+	}
+	if (displayCandidates.length > 1) {
+		throw new SlackError(
+			"ambiguous_user",
+			`Multiple users have display name "${name}": ${displayCandidates.map((u) => u.id).join(", ")}.`,
+		);
+	}
+
+	if (realCandidates.length === 1) {
+		const u = realCandidates[0];
+		mergeAndWrite(ctx.filePath, cached?.team_id ?? (await teamIdFor(ctx.token, ctx.apiCall, ctx.signal)), (base) => {
+			base.users[u.name] = toUserEntry(u);
+		});
+		return u.id;
+	}
+	if (realCandidates.length > 1) {
+		throw new SlackError(
+			"ambiguous_user",
+			`Multiple users have real name "${name}": ${realCandidates.map((u) => u.id).join(", ")}.`,
+		);
+	}
+
+	throw new SlackError("name_not_found", `No user named "${name}" was found in the workspace.`);
+}
+
+const MENTION_DENY = new Set(["here", "channel", "everyone"]);
+const MENTION_BOUNDARY = new Set([" ", "\t", "\n", "\r", "(", "[", "*", "_", '"', "'"]);
+// `_` is trimmed here even though it is also a boundary character: it is a legal username
+// character too, so an italic-wrapped mention like `_@alice_` is otherwise unreachable - the
+// trailing `_` must be stripped for the candidate to resolve.
+const MENTION_TRAILING = /[.,;:!?)_]+$/;
+const MENTION_SCAN = /(\\?)@([A-Za-z0-9._-]+)/g;
+
+function isBoundary(text: string, atIndex: number): boolean {
+	if (atIndex === 0) return true;
+	return MENTION_BOUNDARY.has(text[atIndex - 1]);
+}
+
+/**
+ * Substitutes `@name` -> `<@U...>` across every field a mutation will actually send.
+ * Never throws for an unresolvable name: not-found, ambiguous, and a failed live lookup all
+ * leave the text literal and report it, because a mention is prose, not an addressed parameter.
+ */
+export async function resolveMentions(
+	fields: { field: "text" | "thread_body"; value: string }[],
+	ctx: CacheCtx,
+): Promise<{
+	values: string[];
+	unresolved: UnresolvedMention[];
+	lookupError?: string;
+}> {
+	interface Candidate {
+		field: "text" | "thread_body";
+		start: number;
+		end: number;
+		escaped: boolean;
+		/** [name, endOffsetForThatName] pairs, trimmed variant first so it wins the lookup race. */
+		lookups: [string, number][];
+	}
+
+	const perField: Candidate[][] = fields.map(() => []);
+	const wanted = new Set<string>();
+
+	fields.forEach((f, fi) => {
+		for (const m of f.value.matchAll(MENTION_SCAN)) {
+			const escaped = m[1] === "\\";
+			const at = m.index + m[1].length;
+			if (escaped) {
+				if (!isBoundary(f.value, m.index)) continue;
+			} else if (!isBoundary(f.value, at)) continue;
+
+			const raw = m[2];
+			const fullEnd = m.index + m[0].length;
+			const trimmed = raw.replace(MENTION_TRAILING, "");
+			// Check the deny list against both forms: `_@channel_`/`@here.` still carry the
+			// trailing punctuation stripped below, so a raw-only check misses them.
+			if (MENTION_DENY.has(raw) || MENTION_DENY.has(trimmed)) continue;
+			// A name that is entirely trailing-punctuation (e.g. `@...`) trims to "" - not a
+			// real candidate, so skip it rather than looking up an empty username.
+			if (trimmed === "") continue;
+			const trimmedEnd = fullEnd - (raw.length - trimmed.length);
+			const lookups: [string, number][] =
+				trimmed === raw ? [[raw, fullEnd]] : [[trimmed, trimmedEnd], [raw, fullEnd]];
+			perField[fi].push({ field: f.field, start: m.index, end: fullEnd, escaped, lookups });
+			if (!escaped) for (const [name] of lookups) wanted.add(name);
+		}
+	});
+
+	const cached = readCacheFile(ctx.filePath);
+	const resolved = new Map<string, string>();
+	const aliasTrusted = cached?.snapshot_at !== undefined;
+	// Names an aliasTrusted FULL snapshot already proved ambiguous: a live users.list call
+	// cannot un-ambiguate them, so they must not fall into `outstanding`.
+	const conclusivelyAmbiguous = new Set<string>();
+
+	if (cached) {
+		for (const name of wanted) {
+			const byUsername = cached.users[name];
+			if (byUsername) {
+				resolved.set(name, byUsername.id);
+				continue;
+			}
+			if (!aliasTrusted) continue;
+			const entries = Object.values(cached.users);
+			const display = entries.filter((u) => u.display_name === name);
+			if (display.length === 1) {
+				resolved.set(name, display[0].id);
+				continue;
+			}
+			if (display.length > 1) {
+				conclusivelyAmbiguous.add(name);
+				continue;
+			}
+			const real = entries.filter((u) => u.real_name === name);
+			if (real.length === 1) resolved.set(name, real[0].id);
+			else if (real.length > 1) conclusivelyAmbiguous.add(name);
+		}
+	}
+
+	const outstanding = [...wanted].filter((n) => !resolved.has(n) && !conclusivelyAmbiguous.has(n));
+	let lookupError: string | undefined;
+
+	if (outstanding.length > 0) {
+		try {
+			const found = new Map<string, SlackUser>();
+			const aliasHits = new Map<string, SlackUser[]>();
+			let cursor = "";
+			for (let page = 1; ; page++) {
+				if (page > MAX_LIST_PAGES) {
+					throw new SlackError(
+						"pagination_overflow",
+						`resolveMentions: users.list did not terminate within ${MAX_LIST_PAGES} pages.`,
+					);
+				}
+				const data = await ctx.apiCall(
+					"users.list",
+					ctx.token,
+					{ limit: 1000, ...(cursor ? { cursor } : {}) },
+					{ retry: false, signal: ctx.signal },
+				);
+				for (const u of (data.members as SlackUser[]) ?? []) {
+					for (const name of outstanding) {
+						if (u.name === name) found.set(name, u);
+						else if (u.profile?.display_name === name || (u.profile?.real_name ?? u.real_name) === name) {
+							aliasHits.set(name, [...(aliasHits.get(name) ?? []), u]);
+						}
+					}
+				}
+				const meta = data.response_metadata as { next_cursor?: string } | undefined;
+				const nextCursor = meta?.next_cursor ?? "";
+				if (nextCursor !== "" && nextCursor === cursor) break;
+				cursor = nextCursor;
+				if (!cursor) break;
+			}
+
+			const writes: SlackUser[] = [];
+			for (const name of outstanding) {
+				const exact = found.get(name);
+				const aliases = aliasHits.get(name) ?? [];
+				const pick = exact ?? (aliases.length === 1 ? aliases[0] : undefined);
+				if (!pick) continue;
+				resolved.set(name, pick.id);
+				writes.push(pick);
+			}
+			if (writes.length > 0) {
+				const teamId = cached?.team_id ?? (await teamIdFor(ctx.token, ctx.apiCall, ctx.signal));
+				mergeAndWrite(ctx.filePath, teamId, (base) => {
+					for (const u of writes) base.users[u.name] = toUserEntry(u);
+				});
+			}
+		} catch (err) {
+			lookupError = err instanceof Error ? err.message : String(err);
+		}
+	}
+
+	const unresolved: UnresolvedMention[] = [];
+	const seenUnresolved = new Set<string>();
+	const values = fields.map((f, fi) => {
+		let out = "";
+		let cursor = 0;
+		for (const c of perField[fi]) {
+			out += f.value.slice(cursor, c.start);
+			const literal = f.value.slice(c.start, c.end);
+			if (c.escaped) {
+				out += literal.slice(1);
+				cursor = c.end;
+			} else {
+				const hit = c.lookups.find(([n]) => resolved.has(n));
+				if (hit !== undefined) {
+					out += `<@${resolved.get(hit[0])}>`;
+					cursor = hit[1];
+				} else {
+					out += literal;
+					const name = `@${c.lookups[0][0]}`;
+					// Documented contract (doc/slack.md): unresolvedMentions is deduplicated by
+					// (field, name), so "cc @bob @bob" reports @bob once, not once per occurrence.
+					const key = `${c.field}\u0000${name}`;
+					if (!seenUnresolved.has(key)) {
+						seenUnresolved.add(key);
+						unresolved.push({ field: c.field, name });
+					}
+					cursor = c.end;
+				}
+			}
+		}
+		return out + f.value.slice(cursor);
+	});
+
+	return { values, unresolved, ...(lookupError !== undefined ? { lookupError } : {}) };
+}
+
+/**
+ * Full snapshot replace, deliberately asymmetric with mergeAndWrite: refresh's job is to
+ * atomically overwrite the whole file, so a concurrent mergeAndWrite write racing this one may
+ * be clobbered (last-writer-wins). Accepted per spec (doc/specs/2026-08-29-gh-7-slack-extension.md
+ * Cache section) - a clobbered merge self-heals on the next cache miss.
+ */
+export async function refreshCache(ctx: CacheCtx): Promise<{ channels: number; users: number; emails: number }> {
+	const teamId = await teamIdFor(ctx.token, ctx.apiCall, ctx.signal);
+	const channels: Record<string, string> = {};
+	const users: Record<string, UserEntry> = {};
+
+	let cursor = "";
+	for (let page = 1; ; page++) {
+		if (page > MAX_LIST_PAGES) {
+			throw new SlackError(
+				"pagination_overflow",
+				`refreshCache: conversations.list did not terminate within ${MAX_LIST_PAGES} pages.`,
+			);
+		}
+		const data = await ctx.apiCall(
+			"conversations.list",
+			ctx.token,
+			{ limit: 1000, types: "public_channel,private_channel", ...(cursor ? { cursor } : {}) },
+			{ retry: false, signal: ctx.signal },
+		);
+		const list = (data.channels as { id: string; name: string }[]) ?? [];
+		for (const c of list) channels[c.name] = c.id;
+		const meta = data.response_metadata as { next_cursor?: string } | undefined;
+		const nextCursor = meta?.next_cursor ?? "";
+		// A repeated non-empty cursor never terminates via has_more logic - refresh must not write a
+		// partial cache, so this is a hard overflow, not silent exhaustion (unlike the scan loops).
+		if (nextCursor !== "" && nextCursor === cursor) {
+			throw new SlackError(
+				"pagination_overflow",
+				`refreshCache: conversations.list returned the same cursor twice (${nextCursor}); aborting without writing a partial cache.`,
+			);
+		}
+		cursor = nextCursor;
+		if (!cursor) break;
+	}
+
+	cursor = "";
+	for (let page = 1; ; page++) {
+		if (page > MAX_LIST_PAGES) {
+			throw new SlackError(
+				"pagination_overflow",
+				`refreshCache: users.list did not terminate within ${MAX_LIST_PAGES} pages.`,
+			);
+		}
+		const data = await ctx.apiCall("users.list", ctx.token, { limit: 1000, ...(cursor ? { cursor } : {}) }, { retry: false, signal: ctx.signal });
+		const members = (data.members as SlackUser[]) ?? [];
+		for (const u of members) {
+			users[u.name] = toUserEntry(u);
+		}
+		const meta = data.response_metadata as { next_cursor?: string } | undefined;
+		const nextCursor = meta?.next_cursor ?? "";
+		if (nextCursor !== "" && nextCursor === cursor) {
+			throw new SlackError(
+				"pagination_overflow",
+				`refreshCache: users.list returned the same cursor twice (${nextCursor}); aborting without writing a partial cache.`,
+			);
+		}
+		cursor = nextCursor;
+		if (!cursor) break;
+	}
+
+	const snapshotAt = new Date().toISOString();
+	atomicWrite(ctx.filePath, { team_id: teamId, channels, users, refreshed_at: snapshotAt, snapshot_at: snapshotAt });
+	return {
+		channels: Object.keys(channels).length,
+		users: Object.keys(users).length,
+		emails: Object.values(users).filter((u) => u.email !== undefined).length,
+	};
+}