membot 0.5.2 → 0.7.0

package/src/ingest/converter/xlsx.ts

@@ -0,0 +1,111 @@
+import * as XLSX from "xlsx";
+
+export interface ConvertXlsxOptions {
+	/** Optional sublabel callback driven per-sheet (`parsing 3/8 tabs`). */
+	onProgress?: (sublabel: string) => void;
+}
+
+/**
+ * Convert an XLSX workbook into markdown — one `## <SheetName>`
+ * section per tab, each tab rendered as a GitHub-flavored pipe table
+ * with the first non-empty row treated as the header. Empty sheets
+ * are skipped. Cell values are stringified (numbers, dates, formulas
+ * use their displayed value via `XLSX.utils.format_cell`).
+ *
+ * Pure-JS via SheetJS — no native deps, bundles cleanly with
+ * `bun build --compile`. Yields a macrotask between sheets so
+ * nanospinner's setInterval keeps animating during big workbooks
+ * (otherwise the spinner visibly freezes).
+ */
+export async function convertXlsx(bytes: Uint8Array, opts: ConvertXlsxOptions = {}): Promise<string> {
+	const workbook = XLSX.read(bytes, { type: "array", cellDates: true });
+	const sections: string[] = [];
+	const sheetNames = workbook.SheetNames;
+
+	for (let i = 0; i < sheetNames.length; i++) {
+		const sheetName = sheetNames[i] as string;
+		opts.onProgress?.(`parsing ${i + 1}/${sheetNames.length} tabs`);
+		const sheet = workbook.Sheets[sheetName];
+		if (sheet) {
+			const rows = sheetToMatrix(sheet);
+			const trimmed = trimEmptyEdges(rows);
+			if (trimmed.length > 0) sections.push(`## ${sheetName}\n\n${renderTable(trimmed)}`);
+		}
+		// Yield so the spinner can repaint between sheets — large
+		// workbooks would otherwise freeze the UI for the duration of
+		// the parse.
+		await new Promise<void>((resolve) => setTimeout(resolve, 0));
+	}
+
+	if (sections.length === 0) return "(empty workbook)";
+	return sections.join("\n\n");
+}
+
+/**
+ * Walk every cell in the sheet's used range and produce a 2-D array
+ * of display strings. Uses the cell's formatted text (e.g. dates as
+ * "2026-05-09", percentages as "12.5%") rather than raw values, so
+ * the markdown matches what a human sees in the spreadsheet.
+ */
+function sheetToMatrix(sheet: XLSX.WorkSheet): string[][] {
+	if (!sheet["!ref"]) return [];
+	const range = XLSX.utils.decode_range(sheet["!ref"]);
+	const out: string[][] = [];
+	for (let r = range.s.r; r <= range.e.r; r++) {
+		const row: string[] = [];
+		for (let c = range.s.c; c <= range.e.c; c++) {
+			const addr = XLSX.utils.encode_cell({ r, c });
+			const cell = sheet[addr];
+			row.push(cell ? XLSX.utils.format_cell(cell) : "");
+		}
+		out.push(row);
+	}
+	return out;
+}
+
+/**
+ * Drop fully-empty leading/trailing rows and columns. Spreadsheets
+ * commonly have the used range padded out beyond the actual data.
+ */
+function trimEmptyEdges(rows: string[][]): string[][] {
+	if (rows.length === 0) return rows;
+	let firstRow = 0;
+	let lastRow = rows.length - 1;
+	while (firstRow <= lastRow && rows[firstRow]?.every((v) => v === "")) firstRow++;
+	while (lastRow >= firstRow && rows[lastRow]?.every((v) => v === "")) lastRow--;
+	if (firstRow > lastRow) return [];
+	const sliced = rows.slice(firstRow, lastRow + 1);
+	const cols = sliced[0]?.length ?? 0;
+	let firstCol = 0;
+	let lastCol = cols - 1;
+	while (firstCol <= lastCol && sliced.every((r) => (r[firstCol] ?? "") === "")) firstCol++;
+	while (lastCol >= firstCol && sliced.every((r) => (r[lastCol] ?? "") === "")) lastCol--;
+	if (firstCol > lastCol) return [];
+	return sliced.map((r) => r.slice(firstCol, lastCol + 1));
+}
+
+/**
+ * Render a 2-D matrix as a GitHub pipe table. The first row becomes
+ * the header. Pipe and newline characters in cells are escaped so
+ * they don't break the table layout.
+ */
+function renderTable(rows: string[][]): string {
+	const colCount = Math.max(...rows.map((r) => r.length));
+	const norm = rows.map((r) => {
+		const padded = [...r];
+		while (padded.length < colCount) padded.push("");
+		return padded.map(escapeCell);
+	});
+	const lines: string[] = [];
+	const header = norm[0] ?? Array(colCount).fill("");
+	lines.push(`| ${header.join(" | ")} |`);
+	lines.push(`| ${Array(colCount).fill("---").join(" | ")} |`);
+	for (let i = 1; i < norm.length; i++) {
+		lines.push(`| ${(norm[i] as string[]).join(" | ")} |`);
+	}
+	return lines.join("\n");
+}
+
+function escapeCell(value: string): string {
+	return value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}

package/src/ingest/downloaders/browser.ts

@@ -0,0 +1,180 @@
+import { mkdir } from "node:fs/promises";
+import type { APIRequestContext, BrowserContext, Page } from "playwright";
+import { HelpfulError } from "../../errors.ts";
+
+let chromiumModule: typeof import("playwright").chromium | null = null;
+
+/**
+ * Lazy-import `playwright.chromium`. Keeping the import deferred so the
+ * heavy module isn't loaded on cold paths (e.g. `membot list`); ALSO
+ * lets us produce a `HelpfulError` if Playwright isn't installed yet
+ * instead of a stack trace at module-load time.
+ */
+async function loadChromium(): Promise<typeof import("playwright").chromium> {
+	if (chromiumModule) return chromiumModule;
+	try {
+		const playwright = await import("playwright");
+		chromiumModule = playwright.chromium;
+		return chromiumModule;
+	} catch (err) {
+		throw new HelpfulError({
+			kind: "internal_error",
+			message: `failed to load playwright: ${err instanceof Error ? err.message : String(err)}`,
+			hint: "Run `bun add -g membot` to reinstall, then `bunx playwright install chromium` to fetch the browser binary.",
+		});
+	}
+}
+
+export interface BrowserPoolOptions {
+	userDataDir: string;
+	headless?: boolean;
+}
+
+/**
+ * Process-scoped lazy-launched chromium context backed by a *persistent
+ * profile directory* (`launchPersistentContext`). Persistent profiles
+ * survive cookies, localStorage, sessionStorage, IndexedDB, and service
+ * worker state across runs — necessary for SPA-heavy services like
+ * Linear that stash critical session/sync state in IndexedDB (which
+ * the lighter `storageState` JSON snapshot doesn't capture).
+ *
+ * Trade-offs:
+ *  - The profile is a directory, not a single JSON file (a few MBs).
+ *  - Chromium's single-instance lock means only one BrowserPool can
+ *    have the profile open at a time. Sequential `membot add` calls
+ *    are fine; concurrent CLI processes against the same profile will
+ *    fail to launch.
+ */
+export class BrowserPool {
+	private readonly userDataDir: string;
+	private readonly headless: boolean;
+	private context: BrowserContext | null = null;
+
+	constructor(options: BrowserPoolOptions) {
+		this.userDataDir = options.userDataDir;
+		this.headless = options.headless ?? true;
+	}
+
+	/**
+	 * Lazy-init the persistent context. The first call launches
+	 * chromium against `userDataDir` (creating it if needed); subsequent
+	 * calls reuse the same context so cookies, IDB, and inflight
+	 * navigation state stay shared across downloaders within one run.
+	 */
+	private async ensureContext(): Promise<BrowserContext> {
+		if (this.context) return this.context;
+		const chromium = await loadChromium();
+		await mkdir(this.userDataDir, { recursive: true });
+		try {
+			this.context = await chromium.launchPersistentContext(this.userDataDir, {
+				headless: this.headless,
+			});
+		} catch (err) {
+			throw new HelpfulError({
+				kind: "internal_error",
+				message: `chromium failed to launch: ${err instanceof Error ? err.message : String(err)}`,
+				hint: this.headless
+					? "Run `bunx playwright install chromium` to download the browser binary."
+					: "Close any other membot process holding the browser profile, then retry.",
+			});
+		}
+		return this.context;
+	}
+
+	/** Return the request context for downloaders that just need authenticated HTTP. */
+	async request(): Promise<APIRequestContext> {
+		const ctx = await this.ensureContext();
+		return ctx.request;
+	}
+
+	/** Open a fresh page (caller is responsible for `page.close()`). */
+	async newPage(): Promise<Page> {
+		const ctx = await this.ensureContext();
+		return ctx.newPage();
+	}
+
+	/**
+	 * How many cookies are in the live context. Used by the auth-prompt
+	 * flow to detect "user closed the window without logging in" — must
+	 * be called BEFORE `dispose()` since the context closes its own
+	 * stores when shutting down.
+	 */
+	async cookieCount(): Promise<number> {
+		if (!this.context) return 0;
+		try {
+			const cookies = await this.context.cookies();
+			return cookies.length;
+		} catch {
+			return 0;
+		}
+	}
+
+	/**
+	 * Return the cookies stored in the persistent profile for a given
+	 * URL/origin (or all cookies when omitted). Used by downloaders that
+	 * call services with their own HTTP client (e.g. Node's built-in
+	 * `fetch`) — they read the cookies once here and pass them via a
+	 * `Cookie` header. Bypasses Playwright's APIRequestContext, which
+	 * has a known cookie-parser bug on Google's same-origin redirects.
+	 */
+	async cookieHeader(url: string): Promise<string> {
+		const ctx = await this.ensureContext();
+		const cookies = await ctx.cookies(url);
+		return cookies.map((c) => `${c.name}=${c.value}`).join("; ");
+	}
+
+	/**
+	 * Resolve when the user is "done" with the headed browser session,
+	 * detected as: the supplied page closes, OR its context closes, OR
+	 * the underlying browser disconnects — whichever fires first. We
+	 * can't rely on the browser-disconnect event alone: on macOS,
+	 * closing the last window does NOT quit chromium (the app stays
+	 * alive in the background), so the disconnect event never fires
+	 * and the caller hangs forever. The page-close event is the only
+	 * signal that's consistent across macOS, Linux, and Windows.
+	 */
+	async waitForUserDone(page: Page): Promise<void> {
+		const ctx = page.context();
+		const browser = ctx.browser();
+		await new Promise<void>((resolve) => {
+			let done = false;
+			const finish = () => {
+				if (done) return;
+				done = true;
+				resolve();
+			};
+			page.on("close", finish);
+			ctx.on("close", finish);
+			browser?.on("disconnected", finish);
+			if (page.isClosed() || (browser && !browser.isConnected())) finish();
+		});
+	}
+
+	/** Close the context (which releases the userDataDir lock). Idempotent. */
+	async dispose(): Promise<void> {
+		try {
+			await this.context?.close();
+		} catch {
+			// best-effort
+		}
+		this.context = null;
+	}
+}
+
+/**
+ * Resolve `maybeRelative` against `base` and return a `URL`, or `null`
+ * if neither parses. Playwright's `APIResponse.url()` sometimes hands
+ * back a path-only string (`"/"`) instead of an absolute URL after a
+ * same-origin redirect — every downloader that wants to inspect the
+ * final URL goes through this helper so the relative-URL handling
+ * lives in one place. Login-redirect detection itself is each
+ * downloader's responsibility — it's the only code that knows which
+ * host its export endpoint redirects to when the session is missing.
+ */
+export function safeResolveUrl(maybeRelative: string, base: string): URL | null {
+	try {
+		return new URL(maybeRelative, base);
+	} catch {
+		return null;
+	}
+}

package/src/ingest/downloaders/generic-web.ts

@@ -0,0 +1,81 @@
+import { HelpfulError } from "../../errors.ts";
+import { sha256Hex } from "../local-reader.ts";
+import type { DownloadedRemote, Downloader } from "./index.ts";
+
+/**
+ * Catch-all downloader. Always matches HTTP/HTTPS URLs that no
+ * specific downloader claimed. Strategy:
+ *  - Issue an authenticated GET via Playwright's request context
+ *    (cookies from `membot login` flow through automatically).
+ *  - If the server returned `text/html`, the page is probably a SPA
+ *    or auth-gated render — open a real `page`, wait for
+ *    `networkidle`, and `page.pdf()` the visible result. The rendered
+ *    PDF goes through `convertPdf` so SPAs and login-walled docs
+ *    work uniformly.
+ *  - Otherwise the response IS the file (markdown, JSON, PDF, image,
+ *    docx, …) — return its bytes verbatim and let the mime
+ *    dispatcher pick the right native converter.
+ *
+ * This is what gives "no specific downloader needed" coverage to any
+ * URL the user throws at `membot add`.
+ */
+export const genericWebDownloader: Downloader = {
+	name: "generic-web",
+	description:
+		"Catch-all for any URL no other downloader handled — HEAD/GET, then either page.pdf() the rendered HTML or stream the raw bytes through the mime converter.",
+	matches(url) {
+		return url.protocol === "http:" || url.protocol === "https:";
+	},
+	async download(url, ctx): Promise<DownloadedRemote> {
+		ctx.onProgress?.("fetching");
+		const request = await ctx.pool.request();
+		const response = await request.get(url.toString(), { timeout: 30_000 });
+		// As the catch-all we don't know which login page each unknown
+		// service redirects to. If the user lands on a rendered login
+		// page, it goes through the print-to-PDF path and they'll see
+		// an obviously-wrong "Sign in" PDF — the cue to run `membot login`.
+		// Specific downloaders own auth-redirect detection for the services
+		// they understand.
+		if (!response.ok() && response.status() !== 304) {
+			throw new HelpfulError({
+				kind: "network_error",
+				message: `HTTP ${response.status()} ${response.statusText()}: ${url.toString()}`,
+				hint: "Open the URL in your browser to verify it exists. For auth-gated content, run `membot login` first.",
+			});
+		}
+		const headers = response.headers();
+		const contentType =
+			(headers["content-type"] ?? "application/octet-stream").split(";")[0]?.trim() ?? "application/octet-stream";
+
+		if (contentType === "text/html" || contentType === "application/xhtml+xml") {
+			const page = await ctx.pool.newPage();
+			try {
+				ctx.onProgress?.("rendering page");
+				await page.goto(url.toString(), { waitUntil: "networkidle", timeout: 45_000 });
+				ctx.onProgress?.("printing to pdf");
+				const pdfBuf = await page.pdf({ format: "A4", printBackground: true, preferCSSPageSize: false });
+				const bytes = new Uint8Array(pdfBuf);
+				return {
+					bytes,
+					sha256: sha256Hex(pdfBuf),
+					mimeType: "application/pdf",
+					downloader: "generic-web",
+					downloaderArgs: { rendered: true, source_content_type: contentType },
+					sourceUrl: url.toString(),
+				};
+			} finally {
+				await page.close().catch(() => {});
+			}
+		}
+
+		const body = Buffer.from(await response.body());
+		return {
+			bytes: new Uint8Array(body),
+			sha256: sha256Hex(body),
+			mimeType: contentType,
+			downloader: "generic-web",
+			downloaderArgs: { rendered: false, source_content_type: contentType },
+			sourceUrl: url.toString(),
+		};
+	},
+};

package/src/ingest/downloaders/github.ts

@@ -0,0 +1,178 @@
+import { HelpfulError } from "../../errors.ts";
+import { sha256Hex } from "../local-reader.ts";
+import type { DownloadedRemote, Downloader, DownloaderCtx } from "./index.ts";
+
+const ISSUE_OR_PR = /^\/([^/]+)\/([^/]+)\/(issues|pull)\/(\d+)(?:$|\/|#|\?)/;
+
+const API_BASE = "https://api.github.com";
+
+/**
+ * GitHub issues and PRs via the REST API. The user sets a personal
+ * access token once via `membot config set downloaders.github.api_key
+ * <PAT>` (or via the `GITHUB_TOKEN` env var, which `gh auth token`
+ * happens to populate), and we fetch the issue/PR + every comment as
+ * structured JSON, then render to markdown.
+ *
+ * Why API instead of rendering github.com HTML: the rendered page
+ * works for public, network-cooperative cases but stalls when GitHub
+ * shows interstitials (rate-limit, abuse, login challenges) and
+ * captures hundreds of KB of GitHub chrome that the embedder doesn't
+ * care about. The API gives us the exact body and comment thread in
+ * a few KB.
+ *
+ * Public repos: the `api_key` is optional — we'll send unauthenticated
+ * requests if it's blank, which works for public content but gets
+ * rate-limited at 60 req/hr. Private repos require the token.
+ */
+export const githubDownloader: Downloader = {
+	name: "github",
+	description: "GitHub issues + PRs (github.com/<owner>/<repo>/(issues|pull)/<n>) — uses the GitHub REST API.",
+	logins: [
+		{
+			kind: "api_key",
+			name: "GitHub",
+			url: "https://github.com/settings/tokens",
+			setupCommand: "membot config set downloaders.github.api_key <PAT>",
+			description: "create a fine-grained token with repo:read access (or use GITHUB_TOKEN env var)",
+		},
+	],
+	requiresApiKey: false,
+	matches(url) {
+		return url.hostname === "github.com" && ISSUE_OR_PR.test(url.pathname);
+	},
+	async download(url, ctx): Promise<DownloadedRemote> {
+		const args = parseIssueUrl(url);
+		const owner = args.owner as string;
+		const repo = args.repo as string;
+		const number = args.number as number;
+
+		const token = (ctx.config.downloaders.github.api_key || process.env.GITHUB_TOKEN || "").trim();
+		ctx.onProgress?.("fetching issue");
+		const issue = await getJson<GithubIssue>(`/repos/${owner}/${repo}/issues/${number}`, token, url);
+		ctx.onProgress?.("fetching comments");
+		const comments = await getJson<GithubComment[]>(
+			`/repos/${owner}/${repo}/issues/${number}/comments?per_page=100`,
+			token,
+			url,
+		);
+
+		const isPullRequest = !!issue.pull_request;
+		const markdown = renderIssue(issue, comments, isPullRequest);
+		const bytes = new TextEncoder().encode(markdown);
+		return {
+			bytes,
+			sha256: sha256Hex(bytes),
+			mimeType: "text/markdown",
+			downloader: "github",
+			downloaderArgs: args,
+			sourceUrl: url.toString(),
+		};
+	},
+};
+
+interface GithubIssue {
+	number: number;
+	title: string;
+	body: string | null;
+	state: string;
+	html_url: string;
+	user: { login: string } | null;
+	assignees: Array<{ login: string }> | null;
+	labels: Array<{ name: string } | string> | null;
+	created_at: string;
+	updated_at: string;
+	closed_at: string | null;
+	pull_request?: unknown;
+}
+
+interface GithubComment {
+	body: string | null;
+	user: { login: string } | null;
+	created_at: string;
+}
+
+async function getJson<T>(path: string, token: string, url: URL): Promise<T> {
+	const headers: Record<string, string> = {
+		Accept: "application/vnd.github+json",
+		"X-GitHub-Api-Version": "2022-11-28",
+		"User-Agent": "membot",
+	};
+	if (token !== "") headers.Authorization = `Bearer ${token}`;
+
+	const response = await fetch(`${API_BASE}${path}`, { headers });
+	if (response.status === 401 || response.status === 403) {
+		throw new HelpfulError({
+			kind: "auth_error",
+			message: `GitHub API returned ${response.status} for ${url.toString()}.`,
+			hint:
+				token === ""
+					? "Set a personal access token: create one at https://github.com/settings/tokens, then `membot config set downloaders.github.api_key <PAT>` (or set $GITHUB_TOKEN)."
+					: "The configured API key is missing repo:read access for this repo, or has expired. Re-create the token and run `membot config set downloaders.github.api_key <PAT>`.",
+		});
+	}
+	if (response.status === 404) {
+		throw new HelpfulError({
+			kind: "not_found",
+			message: `GitHub returned 404 for ${url.toString()}.`,
+			hint: "Verify the URL exists. Private repos require an API key with the right scope.",
+		});
+	}
+	if (!response.ok) {
+		throw new HelpfulError({
+			kind: "network_error",
+			message: `GitHub API returned ${response.status} ${response.statusText} for ${url.toString()}.`,
+			hint: "Retry; if the failure persists, run with --verbose for the full response.",
+		});
+	}
+	return (await response.json()) as T;
+}
+
+function parseIssueUrl(url: URL): Record<string, unknown> {
+	const match = url.pathname.match(ISSUE_OR_PR);
+	if (!match) {
+		throw new HelpfulError({
+			kind: "input_error",
+			message: `not a GitHub issue/PR URL: ${url.toString()}`,
+			hint: "Pass a URL like https://github.com/<owner>/<repo>/issues/<n> or .../pull/<n>.",
+		});
+	}
+	return { owner: match[1], repo: match[2], kind: match[3], number: Number(match[4]) };
+}
+
+function renderIssue(issue: GithubIssue, comments: GithubComment[], isPr: boolean): string {
+	const lines: string[] = [];
+	const kind = isPr ? "PR" : "Issue";
+	lines.push(`# ${kind} #${issue.number}: ${issue.title}`);
+	lines.push("");
+	lines.push(`- URL: ${issue.html_url}`);
+	lines.push(`- State: ${issue.state}${issue.closed_at ? ` (closed ${issue.closed_at})` : ""}`);
+	if (issue.user) lines.push(`- Author: @${issue.user.login}`);
+	if (issue.assignees && issue.assignees.length > 0) {
+		lines.push(`- Assignees: ${issue.assignees.map((a) => `@${a.login}`).join(", ")}`);
+	}
+	if (issue.labels && issue.labels.length > 0) {
+		const labels = issue.labels.map((l) => (typeof l === "string" ? l : l.name)).filter(Boolean);
+		if (labels.length > 0) lines.push(`- Labels: ${labels.join(", ")}`);
+	}
+	lines.push(`- Created: ${issue.created_at}`);
+	lines.push(`- Updated: ${issue.updated_at}`);
+	lines.push("");
+	if (issue.body && issue.body.trim() !== "") {
+		lines.push("## Description");
+		lines.push("");
+		lines.push(issue.body.trim());
+		lines.push("");
+	}
+	if (comments.length > 0) {
+		lines.push(`## Comments (${comments.length})`);
+		lines.push("");
+		for (const c of comments) {
+			const author = c.user ? `@${c.user.login}` : "(unknown)";
+			lines.push(`### ${author} — ${c.created_at}`);
+			lines.push("");
+			lines.push((c.body ?? "").trim());
+			lines.push("");
+		}
+	}
+	return lines.join("\n").trim();
+}

package/src/ingest/downloaders/google-docs.ts

@@ -0,0 +1,56 @@
+import { HelpfulError } from "../../errors.ts";
+import { sha256Hex } from "../local-reader.ts";
+import { fetchWithBrowserCookies } from "./google-shared.ts";
+import type { DownloadedRemote, Downloader } from "./index.ts";
+
+const DOC_PATH = /^\/document\/d\/([a-zA-Z0-9_-]+)/;
+const DOCX_MIME = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+
+/**
+ * Download a Google Doc as a `.docx` blob via the canonical export
+ * endpoint. Authentication uses cookies pulled from the persistent
+ * chromium profile (populated by `membot login`); the fetch itself
+ * is a plain Node `fetch`, not Playwright's APIRequestContext, to
+ * dodge a Playwright bug that crashes parsing Set-Cookie headers
+ * from Google's same-origin redirects.
+ */
+export const googleDocsDownloader: Downloader = {
+	name: "google-docs",
+	description: "Google Docs (docs.google.com/document/d/<id>) — exports as .docx via the user's logged-in session.",
+	logins: [
+		{
+			kind: "browser",
+			name: "Google",
+			url: "https://accounts.google.com/signin",
+			description: "covers Docs, Sheets, and Slides",
+		},
+	],
+	matches(url) {
+		return url.hostname === "docs.google.com" && DOC_PATH.test(url.pathname);
+	},
+	async download(url, ctx): Promise<DownloadedRemote> {
+		const docId = extractDocId(url);
+		const exportUrl = `https://docs.google.com/document/d/${docId}/export?format=docx`;
+		const body = await fetchWithBrowserCookies(exportUrl, ctx, "Google Docs", url);
+		return {
+			bytes: new Uint8Array(body),
+			sha256: sha256Hex(body),
+			mimeType: DOCX_MIME,
+			downloader: "google-docs",
+			downloaderArgs: { document_id: docId },
+			sourceUrl: url.toString(),
+		};
+	},
+};
+
+function extractDocId(url: URL): string {
+	const match = url.pathname.match(DOC_PATH);
+	if (!match || !match[1]) {
+		throw new HelpfulError({
+			kind: "input_error",
+			message: `not a Google Docs URL: ${url.toString()}`,
+			hint: "Pass a URL like https://docs.google.com/document/d/<DOC_ID>/edit.",
+		});
+	}
+	return match[1];
+}

package/src/ingest/downloaders/google-shared.ts

@@ -0,0 +1,86 @@
+import { HelpfulError } from "../../errors.ts";
+import type { DownloaderCtx } from "./index.ts";
+
+const USER_AGENT =
+	"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36";
+
+/**
+ * Fetch a Google export URL using cookies from the persistent
+ * chromium profile. Uses Node's built-in `fetch` (not Playwright's
+ * APIRequestContext) because Playwright crashes when parsing
+ * Set-Cookie headers on same-origin Google redirects (its
+ * `_parseSetCookieHeader` calls `new URL(responseUrl)` with a
+ * relative path and throws `ERR_INVALID_URL`).
+ *
+ * Same redirect handling rules as the Playwright path used to do:
+ * follow same-origin internal redirects (Google may bounce the
+ * download via `/exportInternal` or similar) but bail with a clean
+ * `auth_error` if Google sends us to `accounts.google.com/ServiceLogin`
+ * because the user isn't signed in.
+ */
+export async function fetchWithBrowserCookies(
+	exportUrl: string,
+	ctx: DownloaderCtx,
+	serviceName: string,
+	sourceUrl: URL,
+): Promise<Buffer> {
+	ctx.onProgress?.(`downloading from ${serviceName.toLowerCase()}`);
+	const cookieHeader = await ctx.pool.cookieHeader(exportUrl);
+
+	let currentUrl = exportUrl;
+	for (let hop = 0; hop < 5; hop++) {
+		const response = await fetch(currentUrl, {
+			headers: {
+				Cookie: cookieHeader,
+				"User-Agent": USER_AGENT,
+				Accept: "*/*",
+			},
+			redirect: "manual",
+		});
+
+		if (response.status >= 200 && response.status < 300) {
+			return Buffer.from(await response.arrayBuffer());
+		}
+
+		if (response.status >= 300 && response.status < 400) {
+			const location = response.headers.get("location");
+			if (!location) {
+				throw new HelpfulError({
+					kind: "network_error",
+					message: `${serviceName} returned ${response.status} for ${sourceUrl.toString()} with no Location header.`,
+					hint: "Open the URL in your browser to verify it exists and is shared with you.",
+				});
+			}
+			const next = new URL(location, currentUrl);
+			if (next.hostname === "accounts.google.com" || /\/ServiceLogin/i.test(next.pathname)) {
+				throw new HelpfulError({
+					kind: "auth_error",
+					message: `${serviceName} redirected ${sourceUrl.toString()} to a Google login page.`,
+					hint: "Run `membot login` and sign into Google in the browser that opens, then re-run.",
+				});
+			}
+			currentUrl = next.toString();
+			continue;
+		}
+
+		if (response.status === 401 || response.status === 403) {
+			throw new HelpfulError({
+				kind: "auth_error",
+				message: `${serviceName} returned ${response.status} for ${sourceUrl.toString()}.`,
+				hint: "Run `membot login` and sign into Google in the browser that opens, then re-run.",
+			});
+		}
+
+		throw new HelpfulError({
+			kind: "network_error",
+			message: `${serviceName} returned ${response.status} ${response.statusText} for ${sourceUrl.toString()}.`,
+			hint: "Open the URL in your browser to verify it's accessible to your account.",
+		});
+	}
+
+	throw new HelpfulError({
+		kind: "network_error",
+		message: `${serviceName} bounced through too many redirects for ${sourceUrl.toString()}.`,
+		hint: "Re-run the command; if the failure persists, open the URL in your browser to investigate.",
+	});
+}