pin-dl 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1442 @@
+#!/usr/bin/env node
+import { Args, Command, Options } from "@effect/cli";
+import { NodeContext, NodeRuntime } from "@effect/platform-node";
+import { Console, Data, Effect, Option } from "effect";
+import * as fs from "node:fs/promises";
+import * as readline from "node:readline/promises";
+import { execFile, spawn } from "node:child_process";
+import * as path from "node:path";
+import { promisify } from "node:util";
+import { createWriteStream } from "node:fs";
+
+//#region src/domain/errors.ts
+var PinterestHttpError = class extends Data.TaggedError("PinterestHttpError") {};
+var PinterestParseError = class extends Data.TaggedError("PinterestParseError") {};
+var InvalidUrlError = class extends Data.TaggedError("InvalidUrlError") {};
+var DownloadError = class extends Data.TaggedError("DownloadError") {};
+var CacheError = class extends Data.TaggedError("CacheError") {};
+var LoginError = class extends Data.TaggedError("LoginError") {};
+var CaptionError = class extends Data.TaggedError("CaptionError") {};
+
+//#endregion
+//#region src/domain/media.ts
+const isCaptionMode = (s) => s === "txt" || s === "json" || s === "metadata" || s === "none";
+const mediaToDict = (m) => ({
+	id: m.id,
+	src: m.src,
+	alt: m.alt,
+	origin: m.origin,
+	resolution: m.resolution,
+	...m.media_stream ? { media_stream: m.media_stream } : {}
+});
+const dictToMedia = (d) => ({
+	id: d.id,
+	src: d.src,
+	alt: d.alt,
+	origin: d.origin,
+	resolution: d.resolution,
+	...d.media_stream ? { media_stream: d.media_stream } : {}
+});
+
+//#endregion
+//#region src/storage/cache.ts
+/** Save scraped media items to a JSON cache file. */
+const writeCacheFile = (items, cachePath) => Effect.tryPromise({
+	try: async () => {
+		const dicts = items.map(mediaToDict);
+		await fs.writeFile(cachePath, JSON.stringify(dicts, null, 4), "utf-8");
+	},
+	catch: (e) => new CacheError({
+		path: cachePath,
+		message: `Failed to write cache: ${String(e)}`,
+		cause: e
+	})
+});
+/** Read media items from a JSON cache file. */
+const readCacheFile = (cachePath) => Effect.tryPromise({
+	try: async () => {
+		const content = await fs.readFile(cachePath, "utf-8");
+		const raw = JSON.parse(content);
+		if (!Array.isArray(raw)) throw new Error("Cache file must contain a JSON array");
+		return raw.map((d) => dictToMedia(d));
+	},
+	catch: (e) => new CacheError({
+		path: cachePath,
+		message: `Failed to read cache: ${String(e)}`,
+		cause: e
+	})
+});
+/** Load a Selenium-format cookies JSON file. */
+const readCookiesFile = (cookiesPath) => Effect.tryPromise({
+	try: async () => {
+		const content = await fs.readFile(cookiesPath, "utf-8");
+		const raw = JSON.parse(content);
+		if (!Array.isArray(raw)) throw new Error("Cookies file must contain a JSON array");
+		return raw;
+	},
+	catch: (e) => new CacheError({
+		path: cookiesPath,
+		message: `Failed to read cookies file: ${String(e)}`,
+		cause: e
+	})
+});
+/** Save Selenium-format cookies to a JSON file. */
+const writeCookiesFile = (cookies, outputPath) => Effect.tryPromise({
+	try: async () => {
+		await fs.writeFile(outputPath, JSON.stringify(cookies, null, 4), "utf-8");
+	},
+	catch: (e) => new CacheError({
+		path: outputPath,
+		message: `Failed to write cookies file: ${String(e)}`,
+		cause: e
+	})
+});
+
+//#endregion
+//#region src/cli/commands/login.ts
+const promptText = async (prompt) => {
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stderr
+	});
+	try {
+		return await rl.question(prompt);
+	} finally {
+		rl.close();
+	}
+};
+const promptPassword = async (prompt) => {
+	process.stderr.write(prompt);
+	return new Promise((resolve) => {
+		const chunks = [];
+		process.stdin.setRawMode?.(true);
+		process.stdin.resume();
+		process.stdin.setEncoding("utf-8");
+		const onData = (chunk) => {
+			if (chunk === "\r" || chunk === "\n") {
+				process.stdin.setRawMode?.(false);
+				process.stdin.pause();
+				process.stdin.removeListener("data", onData);
+				process.stderr.write("\n");
+				resolve(chunks.join(""));
+			} else if (chunk === "") process.exit(1);
+			else if (chunk === "") chunks.pop();
+			else chunks.push(chunk);
+		};
+		process.stdin.on("data", onData);
+	});
+};
+const runLogin = (options) => Effect.gen(function* () {
+	const email = yield* Effect.tryPromise({
+		try: () => promptText("Enter Pinterest email: "),
+		catch: (e) => new LoginError({
+			message: `Failed to read email: ${String(e)}`,
+			cause: e
+		})
+	});
+	const password = yield* Effect.tryPromise({
+		try: () => promptPassword("Enter Pinterest password: "),
+		catch: (e) => new LoginError({
+			message: `Failed to read password: ${String(e)}`,
+			cause: e
+		})
+	});
+	yield* Console.log(`\nOpening browser — log in manually, then wait ${options.wait}s for cookies to be captured...`);
+	const { chromium, firefox, webkit } = yield* Effect.tryPromise({
+		try: () => import("playwright"),
+		catch: (e) => new LoginError({
+			message: "playwright is not installed. Run: pnpm add playwright && npx playwright install chromium",
+			cause: e
+		})
+	});
+	const browserType = options.client === "firefox" ? firefox : options.client === "webkit" ? webkit : chromium;
+	const browserName = browserType.name();
+	const customExecutable = options.browserExecutable ?? process.env["pin-dl_BROWSER_EXECUTABLE"] ?? void 0;
+	if (customExecutable) yield* Console.log(`[info] Using custom browser executable: ${customExecutable}`);
+	const playwrightExecutable = browserType.executablePath();
+	if (!(customExecutable !== void 0 || (yield* Effect.promise(() => fs.access(playwrightExecutable).then(() => true).catch(() => false))))) {
+		if ((yield* Effect.tryPromise({
+			try: () => promptText(`\n[!] The ${browserName} browser binary is not installed.\n    Expected at: ${playwrightExecutable}\n    Install it now? (may download several hundred MB) [Y/n]: `),
+			catch: (e) => new LoginError({
+				message: `Failed to read install prompt: ${String(e)}`,
+				cause: e
+			})
+		})).trim().toLowerCase() === "n") return yield* Effect.fail(new LoginError({
+			message: `${browserName} is not installed. Run manually:\n  npx playwright install ${browserName}`,
+			cause: null
+		}));
+		yield* Console.log(`\nInstalling ${browserName}...`);
+		yield* Effect.tryPromise({
+			try: () => new Promise((resolve, reject) => {
+				spawn("npx", [
+					"playwright",
+					"install",
+					browserName
+				], {
+					stdio: "inherit",
+					shell: true
+				}).on("close", (code) => {
+					if (code === 0) resolve();
+					else reject(/* @__PURE__ */ new Error(`playwright install exited with code ${code}`));
+				});
+			}),
+			catch: (e) => new LoginError({
+				message: `Failed to install ${browserName}: ${String(e)}`,
+				cause: e
+			})
+		});
+	}
+	const chromiumArgs = options.client === "chromium" ? [
+		"--disable-blink-features=AutomationControlled",
+		"--disable-dev-shm-usage",
+		"--no-sandbox",
+		"--disable-web-security",
+		"--disable-features=IsolateOrigins,site-per-process"
+	] : void 0;
+	const browser = yield* Effect.tryPromise({
+		try: () => browserType.launch({
+			headless: !options.headful,
+			args: chromiumArgs,
+			...customExecutable ? { executablePath: customExecutable } : {}
+		}),
+		catch: (e) => new LoginError({
+			message: `Failed to launch browser: ${String(e)}`,
+			cause: e
+		})
+	});
+	const context = yield* Effect.tryPromise({
+		try: () => browser.newContext({
+			userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+			viewport: {
+				width: 1366,
+				height: 768
+			},
+			locale: "en-US",
+			timezoneId: "America/New_York",
+			colorScheme: "light"
+		}),
+		catch: (e) => new LoginError({
+			message: `Failed to create browser context: ${String(e)}`,
+			cause: e
+		})
+	});
+	const page = yield* Effect.tryPromise({
+		try: () => context.newPage(),
+		catch: (e) => new LoginError({
+			message: `Failed to open page: ${String(e)}`,
+			cause: e
+		})
+	});
+	yield* Effect.tryPromise({
+		try: async () => {
+			await page.goto("https://www.pinterest.com/login/");
+			await page.waitForSelector("input[id=\"email\"]", { timeout: 1e4 });
+			await page.fill("input[id=\"email\"]", email);
+			await page.fill("input[id=\"password\"]", password);
+			await page.click("button[type=\"submit\"]");
+			await new Promise((r) => setTimeout(r, options.wait * 1e3));
+		},
+		catch: (e) => new LoginError({
+			message: `Browser login failed: ${String(e)}`,
+			cause: e
+		})
+	});
+	const cookies = yield* Effect.tryPromise({
+		try: () => context.cookies(),
+		catch: (e) => new LoginError({
+			message: `Failed to capture cookies: ${String(e)}`,
+			cause: e
+		})
+	});
+	yield* Effect.tryPromise({
+		try: () => browser.close(),
+		catch: () => void 0
+	});
+	const isAuthenticated = cookies.find((c) => c.name === "_auth")?.value === "1";
+	yield* writeCookiesFile(cookies, options.output);
+	if (!isAuthenticated) {
+		yield* Console.log("\n[WARNING] Login may have failed!");
+		yield* Console.log("The captured cookies do not indicate an authenticated session (_auth != 1).");
+		yield* Console.log("This usually means credentials were wrong, a captcha was shown,");
+		yield* Console.log(`or not enough time was given (try --headful and --wait ${options.wait + 20}).`);
+		yield* Console.log(`\nCookies saved to '${options.output}' but may not work for private boards.`);
+	} else {
+		yield* Console.log(`\n[SUCCESS] Authenticated cookies saved to '${options.output}'`);
+		yield* Console.log("\nNote: Keep your cookies file safe — do not share it.");
+		yield* Console.log(`Use: pin-dl scrape <url> -o ./output --cookies ${options.output}`);
+	}
+});
+const loginCommand = Command.make("login", {
+	output: Options.withDefault(Options.text("output").pipe(Options.withAlias("o")), "cookies.json"),
+	client: Options.withDefault(Options.text("client").pipe(Options.withDescription("Browser engine to use: chromium | firefox | webkit (default: chromium)")), "chromium"),
+	browserExecutable: Options.optional(Options.text("browser-executable").pipe(Options.withDescription("Path to a custom browser executable instead of Playwright's managed binary. Skips the install check. Also readable from the pin-dl_BROWSER_EXECUTABLE environment variable."))),
+	headful: Options.boolean("headful"),
+	incognito: Options.boolean("incognito"),
+	wait: Options.withDefault(Options.integer("wait"), 10),
+	verbose: Options.boolean("verbose")
+}, (opts) => runLogin({
+	...opts,
+	browserExecutable: opts.browserExecutable._tag === "Some" ? opts.browserExecutable.value : void 0
+}).pipe(Effect.catchAll((e) => Console.error(`Error: ${String(e)}`))));
+
+//#endregion
+//#region src/api/client.ts
+const USER_AGENT = "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36";
+const PWS_HANDLER = "www/pin/[id].js";
+/** Convert cookies to a Cookie header string. */
+const cookiesToString = (cookies) => cookies.map((c) => `${c.name}=${c.value}`).join("; ");
+/** Fetch default cookies from Pinterest's homepage. */
+const getDefaultCookies = () => Effect.tryPromise({
+	try: async () => {
+		return (await fetch("https://www.pinterest.com", {
+			headers: { "User-Agent": USER_AGENT },
+			redirect: "follow"
+		})).headers.getSetCookie().map((h) => h.split(";")[0].trim()).join("; ");
+	},
+	catch: (e) => new PinterestHttpError({
+		message: `Failed to get default cookies from Pinterest: ${String(e)}`,
+		cause: e
+	})
+});
+/**
+* Create a Pinterest session.
+* Fetches default cookies from pinterest.com, optionally merging in user-provided
+* cookies (from a cookies.json file loaded as Selenium format).
+*/
+const makeSession = (customCookies) => Effect.gen(function* () {
+	const parts = [yield* getDefaultCookies()];
+	if (customCookies && customCookies.length > 0) parts.push(cookiesToString(customCookies));
+	return { cookies: parts.join("; ") };
+});
+/** Make an authenticated GET request to a Pinterest API endpoint. */
+const apiGet = (session, url, timeout = 1e4) => Effect.tryPromise({
+	try: async () => {
+		const response = await fetch(url, {
+			signal: AbortSignal.timeout(timeout),
+			headers: {
+				Cookie: session.cookies,
+				"User-Agent": USER_AGENT,
+				"x-pinterest-pws-handler": PWS_HANDLER,
+				"X-Requested-With": "XMLHttpRequest",
+				Accept: "application/json, text/javascript, */*, q=0.01"
+			}
+		});
+		const body = await response.json().catch(() => null);
+		if (!response.ok) {
+			const apiMsg = body?.resource_response?.error?.message;
+			throw new Error(apiMsg ?? `HTTP ${response.status} ${response.statusText}`);
+		}
+		return body;
+	},
+	catch: (e) => new PinterestHttpError({
+		message: `API request failed: ${String(e)}`,
+		cause: e
+	})
+});
+
+//#endregion
+//#region src/api/endpoints.ts
+const BASE = "https://www.pinterest.com";
+const Endpoints = {
+	BASE,
+	GET_RELATED_MODULES: `${BASE}/resource/RelatedModulesResource/get/`,
+	GET_PIN: `${BASE}/resource/PinResource/get/`,
+	GET_MAIN_IMAGE: `${BASE}/resource/ApiResource/get/`,
+	GET_BOARD: `${BASE}/resource/BoardResource/get/`,
+	GET_BOARD_PIN: `${BASE}/resource/BoardFeedResource/get/`,
+	GET_BOARD_SECTIONS: `${BASE}/resource/BoardSectionsResource/get/`,
+	GET_BOARD_SECTION_PINS: `${BASE}/resource/BoardSectionPinsResource/get/`,
+	GET_SEARCH: `${BASE}/resource/BaseSearchResource/get/`
+};
+
+//#endregion
+//#region src/api/request-builder.ts
+/**
+* Mirrors pinterest-dl's Python request_builder.py.
+* Builds GET request URLs with query params in the format Pinterest's API expects:
+*   {endpoint}?source_url={url}&data={JSON}&_={timestamp}
+* Spaces are encoded as %20 (not +).
+*/
+const buildGetUrl = (endpoint, options, sourceUrl = "/", context = {}) => {
+	const data = JSON.stringify({
+		options,
+		context
+	});
+	return `${endpoint}?${new URLSearchParams({
+		source_url: sourceUrl,
+		data,
+		_: Date.now().toString()
+	}).toString().replace(/\+/g, "%20")}`;
+};
+
+//#endregion
+//#region src/api/response-parser.ts
+/** Narrow an unknown value to a plain object record, or return null. */
+const asRecord = (val) => typeof val === "object" && val !== null && !Array.isArray(val) ? val : null;
+/** Extract the highest-resolution video variant from a pin item. */
+const extractBestVideoVariant = (pin) => {
+	const videoList = pin.videos?.video_list ?? pin.story_pin_data?.pages?.[0]?.blocks?.[0]?.video?.video_list ?? {};
+	const variants = Object.values(videoList);
+	if (variants.length === 0) return null;
+	const best = variants.reduce((prev, curr) => {
+		const prevPx = (prev.width ?? 0) * (prev.height ?? 0);
+		return (curr.width ?? 0) * (curr.height ?? 0) > prevPx ? curr : prev;
+	});
+	if (!best.url) return null;
+	return {
+		url: best.url,
+		resolution: [best.width ?? 0, best.height ?? 0],
+		duration: best.duration ?? 0
+	};
+};
+/**
+* Parse a list of raw pin items from the Pinterest API into PinterestMedia objects.
+* Mirrors ResponseParser.from_responses() in the Python code.
+*/
+const parseResponseItems = (items, minResolution = [0, 0], captionFromTitle = false) => {
+	const [minWidth, minHeight] = minResolution;
+	const result = [];
+	for (const item of items) {
+		if (typeof item !== "object" || item === null) continue;
+		const pin = item;
+		const orig = pin.images?.orig;
+		if (!orig?.url) continue;
+		const width = orig.width ?? 0;
+		const height = orig.height ?? 0;
+		if (width < minWidth || height < minHeight) continue;
+		const id = String(pin.id ?? "0");
+		const src = orig.url;
+		const alt = captionFromTitle ? (pin.title ?? pin.auto_alt_text ?? null) || null : (pin.auto_alt_text ?? null) || null;
+		const origin = `https://www.pinterest.com/pin/${id}/`;
+		const videoStream = extractBestVideoVariant(pin);
+		result.push({
+			id,
+			src,
+			alt,
+			origin,
+			resolution: {
+				x: width,
+				y: height
+			},
+			...videoStream ? { media_stream: { video: videoStream } } : {}
+		});
+	}
+	return result;
+};
+/** Validate and extract `resource_response.data` as a single-item array (for PinResource). */
+const extractPinData = (raw) => Effect.gen(function* () {
+	const rawRecord = asRecord(raw);
+	if (rawRecord === null) return yield* Effect.fail(new PinterestParseError({ message: "Response is not an object" }));
+	const rr = asRecord(rawRecord["resource_response"]);
+	if (rr === null) return yield* Effect.fail(new PinterestParseError({ message: "Missing 'resource_response' key" }));
+	const data = rr["data"];
+	if (data === null || data === void 0) return [];
+	return Array.isArray(data) ? data : [data];
+});
+/** Validate and extract `resource_response.data` (array form for boards/pins). */
+const extractDataArray = (raw) => Effect.gen(function* () {
+	const rawRecord = asRecord(raw);
+	if (rawRecord === null) return yield* Effect.fail(new PinterestParseError({ message: "Response is not an object" }));
+	const rr = asRecord(rawRecord["resource_response"]);
+	if (rr === null) return yield* Effect.fail(new PinterestParseError({ message: "Missing 'resource_response' key" }));
+	const data = rr["data"];
+	return Array.isArray(data) ? data : [];
+});
+/** Validate and extract `resource_response.data.results` (array form for search). */
+const extractSearchResults = (raw) => Effect.gen(function* () {
+	const arr = yield* extractDataArray(raw);
+	if (arr.length === 0) {
+		const data = asRecord(asRecord(asRecord(raw)?.["resource_response"])?.["data"]);
+		if (data !== null) {
+			const results = data["results"];
+			return Array.isArray(results) ? results : [];
+		}
+	}
+	return arr;
+});
+/** Extract bookmarks from a raw Pinterest API response. */
+const extractBookmarks = (raw) => {
+	const bookmarks = asRecord(asRecord(asRecord(raw)?.["resource"])?.["options"])?.["bookmarks"];
+	if (!Array.isArray(bookmarks)) return [];
+	return bookmarks.filter((b) => typeof b === "string");
+};
+/** Extract board ID from a raw Pinterest board API response. */
+const extractBoardId = (raw) => Effect.gen(function* () {
+	const rr = asRecord(asRecord(raw)?.["resource_response"]);
+	if (rr === null) return yield* Effect.fail(new PinterestParseError({ message: "Missing resource_response" }));
+	const data = asRecord(rr["data"]);
+	if (data === null) return yield* Effect.fail(new PinterestParseError({ message: "Expected board data object" }));
+	const id = data["id"];
+	if (typeof id !== "string" || !id) return yield* Effect.fail(new PinterestParseError({ message: `Invalid board id: ${String(id)}` }));
+	return id;
+});
+/** Extract pin count from a raw Pinterest board API response. */
+const extractPinCount = (raw) => {
+	const count = asRecord(asRecord(asRecord(raw)?.["resource_response"])?.["data"])?.["pin_count"];
+	return typeof count === "number" ? count : 0;
+};
+/** Extract sections from a raw Pinterest sections API response. */
+const extractSections = (raw) => {
+	const data = asRecord(asRecord(raw)?.["resource_response"])?.["data"];
+	if (!Array.isArray(data)) return [];
+	return data.filter((item) => typeof item === "object" && item !== null && typeof item["id"] === "string");
+};
+
+//#endregion
+//#region src/scraper/bookmark-manager.ts
+/**
+* Manages pagination bookmarks for Pinterest API requests.
+* Mirrors Python's BookmarkManager class.
+*
+* @param last - Number of bookmarks to keep from the tail (1–4). Controls
+*               how many recent bookmarks are sent to the API per request.
+*/
+var BookmarkManager = class {
+	bookmarks = [];
+	constructor(last) {
+		this.last = last;
+		if (last < 0 || last > 4) throw new Error("last must be 0–4");
+	}
+	add(bookmark) {
+		this.bookmarks.push(bookmark);
+	}
+	addAll(bookmarks) {
+		this.bookmarks.push(...bookmarks);
+	}
+	clear() {
+		this.bookmarks = [];
+	}
+	/** Returns the last `N` bookmarks (or all if fewer than N exist). */
+	get() {
+		if (this.bookmarks.length < this.last) return [...this.bookmarks];
+		return this.bookmarks.slice(-this.last);
+	}
+	getAll() {
+		return [...this.bookmarks];
+	}
+	/** Returns true when Pinterest signals there are no more items. */
+	isAtEnd() {
+		return this.bookmarks.some((b) => b.includes("-end-"));
+	}
+};
+
+//#endregion
+//#region src/scraper/url-parser.ts
+/** Add trailing slash if missing. */
+const sanitizeUrl = (url) => url.endsWith("/") ? url : url + "/";
+/** Parse a Pinterest URL into a structured UrlType. */
+const parsePinterestUrl = (url) => {
+	const pinMatch = /pin\/(\d+)\/?/.exec(url);
+	if (pinMatch) return Effect.succeed({
+		kind: "pin",
+		pinId: pinMatch[1]
+	});
+	const searchMatch = /\/search\/pins\/\?q=([^&]+)/.exec(url);
+	if (searchMatch) {
+		const query = decodeURIComponent(searchMatch[1].replace(/\+/g, " "));
+		return Effect.succeed({
+			kind: "search",
+			query
+		});
+	}
+	const sectionMatch = /https:\/\/(?:[a-z0-9-]+\.)?pinterest\.com\/([A-Za-z0-9_-]+)\/([A-Za-z0-9_-]+)\/([A-Za-z0-9_-]+)\/?$/.exec(url);
+	if (sectionMatch) return Effect.succeed({
+		kind: "section",
+		username: sectionMatch[1],
+		boardname: sectionMatch[2],
+		sectionSlug: sectionMatch[3]
+	});
+	const boardMatch = /https:\/\/(?:[a-z0-9-]+\.)?pinterest\.com\/([A-Za-z0-9_-]+)\/([A-Za-z0-9_-]+)\/?$/.exec(url);
+	if (boardMatch) return Effect.succeed({
+		kind: "board",
+		username: boardMatch[1],
+		boardname: boardMatch[2]
+	});
+	if (/^(?!https?:\/\/).*pinterest\./i.test(url)) return Effect.fail(new InvalidUrlError({
+		url,
+		message: `Cannot parse Pinterest URL: ${url}\n  Hint: URL must start with https:// (e.g. https://www.pinterest.com/user/board/)`
+	}));
+	if (/https?:\/\/(?:[a-z0-9-]+\.)?pinterest\.(?!com)[a-z.]+/i.test(url)) return Effect.fail(new InvalidUrlError({
+		url,
+		message: `Cannot parse Pinterest URL: ${url}\n  Hint: Only pinterest.com URLs are supported. Try converting to https://www.pinterest.com/...`
+	}));
+	return Effect.fail(new InvalidUrlError({
+		url,
+		message: `Cannot parse Pinterest URL: ${url}`
+	}));
+};
+
+//#endregion
+//#region src/scraper/api-scraper.ts
+const DEFAULT_OPTS = {
+	num: 100,
+	minResolution: [0, 0],
+	delay: .2,
+	captionFromTitle: false,
+	ensureAlt: false,
+	timeout: 1e4,
+	verbose: false,
+	dump: void 0,
+	related: false
+};
+/** Incrementing counter for dump file naming, scoped to this module. */
+let _dumpSeq = 0;
+/** Save a request URL and its response JSON to the dump directory. Exported for testing. */
+const dumpPair = (url, response, dumpDir) => Effect.promise(async () => {
+	const n = String(++_dumpSeq).padStart(3, "0");
+	await fs.mkdir(dumpDir, { recursive: true });
+	await fs.writeFile(path.join(dumpDir, `dump-${n}-request.json`), JSON.stringify({ url }, null, 2), "utf-8");
+	await fs.writeFile(path.join(dumpDir, `dump-${n}-response.json`), JSON.stringify(response, null, 2), "utf-8");
+});
+const sleep = (seconds) => Effect.promise(() => new Promise((r) => setTimeout(r, seconds * 1e3)));
+const dedup = (items) => {
+	const seen = /* @__PURE__ */ new Set();
+	return items.filter((m) => {
+		if (seen.has(m.src)) return false;
+		seen.add(m.src);
+		return true;
+	});
+};
+const filterAlt = (items) => items.filter((m) => m.alt && m.alt.trim() !== "");
+/**
+* Retry an Effect on PinterestHttpError with linear backoff.
+* Parse errors and other failures propagate immediately without retry.
+*/
+const withNetworkRetry = (makeEffect, maxAttempts = 3) => {
+	const attempt = (remaining) => makeEffect().pipe(Effect.catchTag("PinterestHttpError", (e) => {
+		if (remaining <= 1) return Effect.fail(e);
+		return sleep(maxAttempts - remaining + 1).pipe(Effect.andThen(attempt(remaining - 1)));
+	}));
+	return attempt(maxAttempts);
+};
+/** Scrape related pins given a pin ID, paginating until `num` items collected. */
+const scrapeRelatedPins = (session, pinId, opts) => Effect.gen(function* () {
+	const bookmarks = new BookmarkManager(3);
+	const results = [];
+	let remains = opts.num;
+	while (remains > 0) {
+		const batchSize = Math.min(50, remains);
+		const pinUrl = buildGetUrl(Endpoints.GET_RELATED_MODULES, {
+			pin_id: pinId,
+			context_pin_ids: [],
+			page_size: batchSize,
+			bookmarks: bookmarks.get(),
+			search_query: "",
+			source: "deep_linking",
+			top_level_source: "deep_linking",
+			top_level_source_depth: 1,
+			is_pdp: false
+		}, `/pin/${pinId}/`);
+		const raw = yield* withNetworkRetry(() => apiGet(session, pinUrl, opts.timeout));
+		if (opts.dump) yield* dumpPair(pinUrl, raw, opts.dump);
+		bookmarks.addAll(extractBookmarks(raw));
+		const batch = parseResponseItems(yield* extractDataArray(raw), opts.minResolution, opts.captionFromTitle);
+		const filtered = opts.ensureAlt ? filterAlt(batch) : batch;
+		const before = results.length;
+		results.push(...filtered);
+		const dedupd = dedup(results);
+		results.length = 0;
+		results.push(...dedupd);
+		remains -= results.length - before;
+		opts.onProgress?.(results.length, opts.num);
+		if (bookmarks.isAtEnd()) break;
+		if (remains > 0) yield* sleep(opts.delay);
+	}
+	return results.slice(0, opts.num);
+});
+/** Fetch a single pin directly by its ID using PinResource. */
+const scrapeSinglePin = (session, pinId, opts) => Effect.gen(function* () {
+	const pinUrl = buildGetUrl(Endpoints.GET_PIN, {
+		id: pinId,
+		field_set_key: "detailed"
+	}, `/pin/${pinId}/`);
+	const raw = yield* withNetworkRetry(() => apiGet(session, pinUrl, opts.timeout));
+	if (opts.dump) yield* dumpPair(pinUrl, raw, opts.dump);
+	const results = parseResponseItems(yield* extractPinData(raw), opts.minResolution, opts.captionFromTitle);
+	const filtered = opts.ensureAlt ? filterAlt(results) : results;
+	opts.onProgress?.(filtered.length, 1);
+	return filtered;
+});
+/** Scrape board pins given username and boardname. */
+const scrapeBoard = (session, username, boardname, opts) => Effect.gen(function* () {
+	const boardInfoUrl = buildGetUrl(Endpoints.GET_BOARD, {
+		username,
+		slug: boardname,
+		field_set_key: "detailed"
+	}, `/${username}/${boardname}/`);
+	const boardRaw = yield* withNetworkRetry(() => apiGet(session, boardInfoUrl, opts.timeout));
+	if (opts.dump) yield* dumpPair(boardInfoUrl, boardRaw, opts.dump);
+	const boardId = yield* extractBoardId(boardRaw);
+	const pinCount = extractPinCount(boardRaw);
+	const target = Math.min(opts.num, pinCount || opts.num);
+	const bookmarks = new BookmarkManager(3);
+	const results = [];
+	let remains = target;
+	let consecutiveEmpty = 0;
+	const MAX_EMPTY = 3;
+	while (remains > 0) {
+		const batchSize = Math.min(50, remains);
+		const boardFeedUrl = buildGetUrl(Endpoints.GET_BOARD_PIN, {
+			board_id: boardId,
+			board_url: `/${username}/${boardname}/`,
+			page_size: batchSize,
+			bookmarks: bookmarks.get(),
+			currentFilter: -1,
+			field_set_key: "react_grid_pin",
+			filter_section_pins: true,
+			sort: "default",
+			layout: "default",
+			redux_normalize_feed: true
+		}, `/${username}/${boardname}/`);
+		const raw = yield* withNetworkRetry(() => apiGet(session, boardFeedUrl, opts.timeout));
+		if (opts.dump) yield* dumpPair(boardFeedUrl, raw, opts.dump);
+		bookmarks.addAll(extractBookmarks(raw));
+		const batch = parseResponseItems(yield* extractDataArray(raw), opts.minResolution, opts.captionFromTitle);
+		const filtered = opts.ensureAlt ? filterAlt(batch) : batch;
+		if (filtered.length === 0) {
+			consecutiveEmpty++;
+			if (consecutiveEmpty >= MAX_EMPTY) break;
+		} else consecutiveEmpty = 0;
+		const before = results.length;
+		results.push(...filtered);
+		const dedupd = dedup(results);
+		results.length = 0;
+		results.push(...dedupd);
+		remains -= results.length - before;
+		opts.onProgress?.(results.length, opts.num);
+		if (bookmarks.isAtEnd()) break;
+		if (remains > 0) yield* sleep(opts.delay);
+	}
+	return results.slice(0, opts.num);
+});
+/** Scrape a specific board section by slug. */
+const scrapeSection = (session, username, boardname, sectionSlug, opts) => Effect.gen(function* () {
+	const sectionBoardInfoUrl = buildGetUrl(Endpoints.GET_BOARD, {
+		username,
+		slug: boardname,
+		field_set_key: "detailed"
+	}, `/${username}/${boardname}/`);
+	const boardRaw = yield* withNetworkRetry(() => apiGet(session, sectionBoardInfoUrl, opts.timeout));
+	if (opts.dump) yield* dumpPair(sectionBoardInfoUrl, boardRaw, opts.dump);
+	const boardId = yield* extractBoardId(boardRaw);
+	const sectionsUrl = buildGetUrl(Endpoints.GET_BOARD_SECTIONS, { board_id: boardId });
+	const sectionsRaw = yield* withNetworkRetry(() => apiGet(session, sectionsUrl, opts.timeout));
+	if (opts.dump) yield* dumpPair(sectionsUrl, sectionsRaw, opts.dump);
+	const section = extractSections(sectionsRaw).find((s) => s.slug === sectionSlug || (s.title ?? "").toLowerCase().replace(/\s+/g, "-") === sectionSlug.toLowerCase());
+	if (!section) return yield* Effect.fail(new InvalidUrlError({
+		url: `/${username}/${boardname}/${sectionSlug}/`,
+		message: `Section '${sectionSlug}' not found in board '${boardname}'`
+	}));
+	const sectionId = section.id;
+	const bookmarks = new BookmarkManager(3);
+	const results = [];
+	let remains = opts.num;
+	while (remains > 0) {
+		const batchSize = Math.min(50, remains);
+		const sectionPinsUrl = buildGetUrl(Endpoints.GET_BOARD_SECTION_PINS, {
+			section_id: sectionId,
+			page_size: batchSize,
+			bookmarks: bookmarks.get(),
+			field_set_key: "react_grid_pin",
+			redux_normalize_feed: true
+		}, `/board/section/${sectionId}/`);
+		const raw = yield* withNetworkRetry(() => apiGet(session, sectionPinsUrl, opts.timeout));
+		if (opts.dump) yield* dumpPair(sectionPinsUrl, raw, opts.dump);
+		bookmarks.addAll(extractBookmarks(raw));
+		const batch = parseResponseItems(yield* extractDataArray(raw), opts.minResolution, opts.captionFromTitle);
+		const filtered = opts.ensureAlt ? filterAlt(batch) : batch;
+		const before = results.length;
+		results.push(...filtered);
+		const dedupd = dedup(results);
+		results.length = 0;
+		results.push(...dedupd);
+		remains -= results.length - before;
+		opts.onProgress?.(results.length, opts.num);
+		if (bookmarks.isAtEnd() || filtered.length === 0) break;
+		if (remains > 0) yield* sleep(opts.delay);
+	}
+	return results.slice(0, opts.num);
+});
+/** Search Pinterest by query string. */
+const scrapeSearch = (session, query, opts) => Effect.gen(function* () {
+	const bookmarks = new BookmarkManager(1);
+	const results = [];
+	let remains = opts.num;
+	const apiSourceUrl = `/search/pins/?q=${encodeURIComponent(query)}rs=typed`;
+	while (remains > 0) {
+		const batchSize = Math.min(50, remains);
+		const searchUrl = buildGetUrl(Endpoints.GET_SEARCH, {
+			appliedProductFilters: "---",
+			auto_correction_disabled: false,
+			bookmarks: bookmarks.get(),
+			page_size: batchSize,
+			query,
+			redux_normalize_feed: true,
+			rs: "typed",
+			scope: "pins",
+			source_url: apiSourceUrl
+		}, apiSourceUrl);
+		const raw = yield* withNetworkRetry(() => apiGet(session, searchUrl, opts.timeout));
+		if (opts.dump) yield* dumpPair(searchUrl, raw, opts.dump);
+		bookmarks.addAll(extractBookmarks(raw));
+		const batch = parseResponseItems(yield* extractSearchResults(raw), opts.minResolution, opts.captionFromTitle);
+		const filtered = opts.ensureAlt ? filterAlt(batch) : batch;
+		const before = results.length;
+		results.push(...filtered);
+		const dedupd = dedup(results);
+		results.length = 0;
+		results.push(...dedupd);
+		remains -= results.length - before;
+		opts.onProgress?.(results.length, opts.num);
+		if (bookmarks.isAtEnd() || filtered.length === 0) break;
+		if (remains > 0) yield* sleep(opts.delay);
+	}
+	return results.slice(0, opts.num);
+});
+/** Scrape a Pinterest URL (pin, board, section, or search). */
+const scrapeUrl = (session, url, opts = {}) => Effect.gen(function* () {
+	const resolved = {
+		...DEFAULT_OPTS,
+		...opts
+	};
+	const parsed = yield* parsePinterestUrl(sanitizeUrl(url));
+	switch (parsed.kind) {
+		case "pin": return resolved.related ? yield* scrapeRelatedPins(session, parsed.pinId, resolved) : yield* scrapeSinglePin(session, parsed.pinId, resolved);
+		case "board": return yield* scrapeBoard(session, parsed.username, parsed.boardname, resolved);
+		case "section": return yield* scrapeSection(session, parsed.username, parsed.boardname, parsed.sectionSlug, resolved);
+		case "search": return yield* scrapeSearch(session, parsed.query, resolved);
+	}
+});
+/** Search Pinterest for a query string. */
+const scrapeQuery = (session, query, opts = {}) => {
+	return scrapeSearch(session, query, {
+		...DEFAULT_OPTS,
+		...opts
+	});
+};
+
+//#endregion
+//#region src/download/downloader.ts
+const execFileAsync = promisify(execFile);
+/**
+* Render a filename template for a single media item.
+* Variables: {id}, {alt}, {index} (1-based).
+* Exported for testing.
+*/
+const renderFilename = (template, media, index) => {
+	const safeAlt = (media.alt ?? "").trim().replace(/[^\w\s-]/g, "").replace(/\s+/g, "_").slice(0, 100).trim() || media.id;
+	return template.replace(/\{id\}/g, media.id).replace(/\{alt\}/g, safeAlt).replace(/\{index\}/g, String(index + 1));
+};
+/** Build ffmpeg arguments for remuxing or re-encoding an HLS stream. Exported for testing. */
+const buildFfmpegArgs = (inputPath, outputPath, reencode) => reencode ? [
+	"-y",
+	"-i",
+	inputPath,
+	outputPath
+] : [
+	"-y",
+	"-i",
+	inputPath,
+	"-c",
+	"copy",
+	outputPath
+];
+const downloadBlob = async (url, dest, timeout = 3e4) => {
+	const response = await fetch(url, {
+		signal: AbortSignal.timeout(timeout),
+		headers: { "User-Agent": USER_AGENT }
+	});
+	if (!response.ok) throw new Error(`HTTP ${response.status}`);
+	await fs.writeFile(dest, new Uint8Array(await response.arrayBuffer()));
+};
+/** Parse an M3U8 playlist and return all segment URLs. */
+const parseM3U8Segments = (content, baseUrl) => {
+	const base = new URL(baseUrl);
+	const segments = [];
+	for (const line of content.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		if (/^https?:\/\//.test(trimmed)) segments.push(trimmed);
+		else {
+			base.pathname = base.pathname.replace(/[^/]+$/, trimmed);
+			segments.push(base.href);
+		}
+	}
+	return segments;
+};
+/** Download an HLS stream. Concatenates .ts segments, optionally remuxes with ffmpeg. */
+const downloadHls = async (streamUrl, targetPath, skipRemux, reencode, timeout = 6e4) => {
+	const response = await fetch(streamUrl, {
+		signal: AbortSignal.timeout(timeout),
+		headers: { "User-Agent": USER_AGENT }
+	});
+	if (!response.ok) throw new Error(`Failed to fetch HLS manifest: HTTP ${response.status}`);
+	const segments = parseM3U8Segments(await response.text(), streamUrl);
+	if (segments.length === 0) throw new Error("No segments found in HLS manifest");
+	const buffers = [];
+	for (const segUrl of segments) {
+		const seg = await fetch(segUrl, {
+			signal: AbortSignal.timeout(timeout),
+			headers: { "User-Agent": USER_AGENT }
+		});
+		if (!seg.ok) throw new Error(`Failed to fetch HLS segment: ${segUrl}`);
+		buffers.push(new Uint8Array(await seg.arrayBuffer()));
+	}
+	const tsBuffer = Buffer.concat(buffers);
+	if (skipRemux && !reencode) {
+		const tsPath = targetPath.replace(/\.mp4$/, ".ts");
+		await fs.writeFile(tsPath, tsBuffer);
+		return tsPath;
+	}
+	const tsPath = targetPath + ".tmp.ts";
+	await fs.writeFile(tsPath, tsBuffer);
+	try {
+		await execFileAsync("ffmpeg", buildFfmpegArgs(tsPath, targetPath, reencode));
+		await fs.rm(tsPath, { force: true });
+		return targetPath;
+	} catch {
+		await fs.rm(tsPath, { force: true }).catch(() => {});
+		const tsOut = targetPath.replace(/\.mp4$/, ".ts");
+		await fs.writeFile(tsOut, tsBuffer);
+		console.warn(`[warn] ffmpeg not found or failed — saved raw .ts file instead: ${tsOut}`);
+		return tsOut;
+	}
+};
+/** Download a single media item to the output directory. */
+const downloadOne = async (media, outputDir, downloadStreams, skipRemux, reencode, skipExisting, filenameTemplate, index) => {
+	await fs.mkdir(outputDir, { recursive: true });
+	const basename = renderFilename(filenameTemplate, media, index);
+	if (downloadStreams && media.media_stream) {
+		const videoUrl = media.media_stream.video.url;
+		const dest = path.join(outputDir, `${basename}.mp4`);
+		if (skipExisting) try {
+			await fs.access(dest);
+			return {
+				...media,
+				localPath: dest
+			};
+		} catch {}
+		if (new URL(videoUrl).pathname.toLowerCase().endsWith(".mp4")) await downloadBlob(videoUrl, dest);
+		else {
+			const actual = await downloadHls(videoUrl, dest, skipRemux, reencode);
+			return {
+				...media,
+				localPath: actual
+			};
+		}
+		return {
+			...media,
+			localPath: dest
+		};
+	}
+	const imageUrl = media.src;
+	const parsedPath = new URL(imageUrl).pathname;
+	const ext = path.extname(parsedPath).toLowerCase() || ".jpg";
+	const dest = path.join(outputDir, `${basename}${ext}`);
+	if (skipExisting) try {
+		await fs.access(dest);
+		return {
+			...media,
+			localPath: dest
+		};
+	} catch {}
+	await downloadBlob(imageUrl, dest);
+	return {
+		...media,
+		localPath: dest
+	};
+};
+/**
+* Download media items concurrently.
+* Returns the same list with `localPath` populated for successfully downloaded items.
+*/
+const downloadMedia = (items, outputDir, downloadStreams = false, skipRemux = false, reencode = false, concurrency = 8, skipExisting = false, filenameTemplate = "{id}") => Effect.gen(function* () {
+	const total = items.length;
+	let done = 0;
+	const indexedItems = items.map((item, i) => [item, i]);
+	const results = yield* Effect.forEach(indexedItems, ([media, i]) => Effect.tryPromise({
+		try: async () => {
+			const result = await downloadOne(media, outputDir, downloadStreams, skipRemux, reencode, skipExisting, filenameTemplate, i);
+			done++;
+			process.stderr.write(`\r  Downloading ${done}/${total}...`);
+			return result;
+		},
+		catch: (e) => new DownloadError({
+			url: media.src,
+			message: `Failed to download ${media.id}: ${String(e)}`,
+			cause: e
+		})
+	}).pipe(Effect.catchTag("DownloadError", (err) => {
+		done++;
+		process.stderr.write(`\r  Downloading ${done}/${total}...`);
+		console.warn(`\n[warn] ${err.message}`);
+		return Effect.succeed(media);
+	})), { concurrency });
+	if (total > 0) process.stderr.write("\n");
+	return results;
+});
+
+//#endregion
+//#region src/storage/captions.ts
+/** Write caption files for downloaded items (txt or json mode). */
+const writeCaptionFiles = (items, outputDir, mode) => Effect.tryPromise({
+	try: async () => {
+		await fs.mkdir(outputDir, { recursive: true });
+		for (const item of items) {
+			if (!item.localPath) continue;
+			const baseName = path.basename(item.localPath, path.extname(item.localPath));
+			if (mode === "txt") {
+				const caption = item.alt ?? "";
+				const capPath = path.join(outputDir, `${baseName}.txt`);
+				await fs.writeFile(capPath, caption, "utf-8");
+			} else if (mode === "json") {
+				const capPath = path.join(outputDir, `${baseName}.json`);
+				await fs.writeFile(capPath, JSON.stringify(mediaToDict(item), null, 2), "utf-8");
+			}
+		}
+	},
+	catch: (e) => new CaptionError({
+		path: outputDir,
+		message: `Failed to write caption files: ${String(e)}`,
+		cause: e
+	})
+});
+/**
+* Route caption writing based on mode.
+* 'metadata' (EXIF embedding) is noted as unsupported in this TS implementation
+* and falls back to printing a warning.
+*/
+const applyCaption = (items, outputDir, mode) => {
+	if (mode === "txt" || mode === "json") return writeCaptionFiles(items, outputDir, mode);
+	if (mode === "metadata") return Effect.sync(() => {
+		console.warn("[warn] EXIF metadata embedding is not supported in this implementation. Use --caption txt or --caption json instead.");
+	});
+	return Effect.void;
+};
+/** Filter items that have alt text (for --ensure-cap). */
+const filterWithAlt = (items) => items.filter((m) => m.alt && m.alt.trim() !== "");
+
+//#endregion
+//#region src/cli/shared-options.ts
+/**
+* Shared CLI option definitions re-used across scrape, search, and download commands.
+*/
+const outputOption = Options.optional(Options.text("output").pipe(Options.withAlias("o"), Options.withDescription("Output directory for downloaded files")));
+const cookiesOption = Options.optional(Options.text("cookies").pipe(Options.withAlias("c"), Options.withDescription("Path to cookies JSON file for private boards")));
+const numOption = Options.withDefault(Options.integer("limit").pipe(Options.withAlias("n"), Options.withDescription("Maximum number of images to scrape (default: 100)")), 100);
+const resolutionOption = Options.optional(Options.text("min-res").pipe(Options.withAlias("r"), Options.withDescription("Minimum resolution filter, e.g. `512x512` — skips images smaller than this")));
+const videoOption = Options.boolean("video").pipe(Options.withDescription("Download video streams if available"));
+const skipRemuxOption = Options.boolean("skip-remux").pipe(Options.withDescription("Skip ffmpeg remux; output raw .ts file"));
+const timeoutOption = Options.withDefault(Options.integer("timeout").pipe(Options.withDescription("Request timeout in seconds (default: 10)")), 10);
+const delayOption = Options.withDefault(Options.text("delay").pipe(Options.withDescription("Delay between requests in seconds (default: 0.2)")), "0.2");
+const cacheOption = Options.optional(Options.text("save-urls").pipe(Options.withDescription("Save scraped URLs to a JSON file for later download with `pin-dl download`")));
+const dryRunOption = Options.boolean("dry-run").pipe(Options.withDescription("Print found URLs to stdout without downloading anything"));
+const skipExistingOption = Options.boolean("skip-existing").pipe(Options.withDescription("Skip files that already exist in the output directory"));
+const captionOption = Options.withDefault(Options.text("caption").pipe(Options.withDescription("Caption format: txt | json | metadata | none (default: none)")), "none");
+const ensureCapOption = Options.boolean("ensure-cap").pipe(Options.withDescription("Only include images that have alt text"));
+const capFromTitleOption = Options.boolean("cap-from-title").pipe(Options.withDescription("Use image title as the caption instead of auto_alt_text"));
+const verboseOption = Options.boolean("verbose").pipe(Options.withDescription("Enable verbose output"));
+const dumpOption = Options.optional(Options.text("dump").pipe(Options.withDescription("Save raw API request/response pairs to this directory for debugging")));
+const relatedOption = Options.boolean("related").pipe(Options.withDescription("For pin URLs: scrape related pins instead of just the linked pin"));
+const filenameOption = Options.withDefault(Options.text("filename").pipe(Options.withDescription("Filename template for downloaded files. Variables: {id} (pin ID), {alt} (sanitized alt text), {index} (1-based). Extension is always appended automatically. Default: {id}")), "{id}");
+const sectionOption = Options.optional(Options.text("section").pipe(Options.withDescription("Board section to scrape, by name. Slugified and appended to the board URL. E.g. --section 'Kitchen Ideas' → .../kitchen-ideas/. Pass the section URL directly for guaranteed accuracy.")));
+const reencodeOption = Options.boolean("reencode").pipe(Options.withDescription("Force re-encode HLS video to MP4 (slower but guaranteed compatibility; overrides --skip-remux)"));
+const logFileOption = Options.optional(Options.text("log-file").pipe(Options.withDescription("Append all log output to this file in addition to the console")));
+/**
+* Tee console.log / console.warn / console.error to a file.
+* Subsequent writes append to the file (flags: 'a').
+*/
+const setupLogFile = (logPath) => {
+	const stream = createWriteStream(logPath, { flags: "a" });
+	const write = (...args) => {
+		stream.write(args.map(String).join(" ") + "\n");
+	};
+	const origLog = console.log.bind(console);
+	const origWarn = console.warn.bind(console);
+	const origError = console.error.bind(console);
+	console.log = (...args) => {
+		origLog(...args);
+		write(...args);
+	};
+	console.warn = (...args) => {
+		origWarn(...args);
+		write(...args);
+	};
+	console.error = (...args) => {
+		origError(...args);
+		write(...args);
+	};
+};
+const fileOption = Options.optional(Options.text("file").pipe(Options.withAlias("f"), Options.withDescription("Path to a file containing URLs/queries (one per line). Use - for stdin.")));
+/** Parse "512x512" → [512, 512] */
+const parseResolution = (res) => {
+	const parts = res.split("x");
+	if (parts.length !== 2) throw new Error(`Invalid resolution format: ${res}. Use WxH, e.g. 512x512`);
+	const w = parseInt(parts[0], 10);
+	const h = parseInt(parts[1], 10);
+	if (isNaN(w) || isNaN(h)) throw new Error(`Invalid resolution: ${res}`);
+	return [w, h];
+};
+/** Parse delay string to a float. */
+const parseDelay = (delay) => {
+	const f = parseFloat(delay);
+	return isNaN(f) ? .2 : f;
+};
+/** Read lines from a file path (or stdin if path === '-'). */
+const readLines = async (filePath) => {
+	const lines = [];
+	if (filePath === "-") {
+		const chunks = [];
+		for await (const chunk of process.stdin) chunks.push(String(chunk));
+		lines.push(...chunks.join("").split("\n").map((l) => l.trim()).filter(Boolean));
+	} else {
+		const { readFile } = await import("node:fs/promises");
+		const content = await readFile(filePath, "utf-8");
+		lines.push(...content.split("\n").map((l) => l.trim()).filter(Boolean));
+	}
+	return lines;
+};
+/** Validate cookie auth: checks for _auth=1. */
+const checkCookiesAuthenticated = (cookies) => {
+	return cookies.find((c) => c.name === "_auth")?.value === "1";
+};
+
+//#endregion
+//#region src/cli/commands/scrape.ts
+const processUrl = (url, opts, session) => Effect.gen(function* () {
+	const minRes = Option.isSome(opts.resolution) ? parseResolution(opts.resolution.value) : [0, 0];
+	yield* Console.log(`Scraping ${url}...`);
+	const media = yield* scrapeUrl(session, url, {
+		num: opts.num,
+		minResolution: minRes,
+		delay: parseDelay(opts.delay),
+		captionFromTitle: opts.capFromTitle,
+		ensureAlt: opts.ensureCap,
+		timeout: opts.timeout * 1e3,
+		verbose: opts.verbose,
+		dump: Option.getOrUndefined(opts.dump),
+		related: opts.related,
+		onProgress: /pin\/\d+/.test(url) && !opts.related ? void 0 : (collected, total) => {
+			process.stderr.write(`\r  Scraped ${collected}/${total}...`);
+		}
+	});
+	if (!(/pin\/\d+/.test(url) && !opts.related)) process.stderr.write("\n");
+	if (opts.dryRun) {
+		for (const m of media) yield* Console.log(m.src);
+		yield* Console.log(`Found ${media.length} item(s).`);
+		if (Option.isSome(opts.cache)) {
+			yield* writeCacheFile(media, opts.cache.value);
+			yield* Console.log(`Saved URLs → ${opts.cache.value}`);
+		}
+		return;
+	}
+	if (opts.verbose) for (const m of media) yield* Console.log(`  ${m.src}`);
+	if (Option.isSome(opts.cache)) {
+		yield* writeCacheFile(media, opts.cache.value);
+		yield* Console.log(`Cached ${media.length} items → ${opts.cache.value}`);
+	}
+	if (Option.isNone(opts.output)) {
+		if (Option.isNone(opts.cache)) yield* Console.log(JSON.stringify(media.map((m) => ({
+			src: m.src,
+			alt: m.alt,
+			origin: m.origin
+		})), null, 2));
+		return;
+	}
+	const outputDir = opts.output.value;
+	const downloaded = yield* downloadMedia(media, outputDir, opts.video, opts.skipRemux, opts.reencode, 8, opts.skipExisting, opts.filename);
+	const captionMode = isCaptionMode(opts.caption) ? opts.caption : "none";
+	if (captionMode !== "none") yield* applyCaption(downloaded, outputDir, captionMode);
+	if (!(/pin\/\d+/.test(url) && !opts.related) && downloaded.length !== opts.num) yield* Console.log(`Note: Got ${downloaded.length} items (requested ${opts.num}). Some may have been filtered, duplicated, or unavailable.`);
+});
+const scrapeCommand = Command.make("scrape", {
+	urls: Args.between(Args.text({ name: "url" }), 0, 999),
+	output: outputOption,
+	file: fileOption,
+	cookies: cookiesOption,
+	num: numOption,
+	resolution: resolutionOption,
+	video: videoOption,
+	skipRemux: skipRemuxOption,
+	reencode: reencodeOption,
+	timeout: timeoutOption,
+	delay: delayOption,
+	cache: cacheOption,
+	caption: captionOption,
+	ensureCap: ensureCapOption,
+	capFromTitle: capFromTitleOption,
+	related: relatedOption,
+	section: sectionOption,
+	filename: filenameOption,
+	verbose: verboseOption,
+	dump: dumpOption,
+	logFile: logFileOption,
+	dryRun: dryRunOption,
+	skipExisting: skipExistingOption
+}, (opts) => Effect.gen(function* () {
+	if (Option.isSome(opts.logFile)) setupLogFile(opts.logFile.value);
+	const autoSavePath = Option.isNone(opts.cache) && Option.isSome(opts.output) ? `${opts.output.value}.json` : null;
+	const effectiveOpts = autoSavePath !== null ? {
+		...opts,
+		cache: Option.some(autoSavePath)
+	} : opts;
+	process.once("SIGINT", () => {
+		if (autoSavePath) process.stderr.write(`\nInterrupted. If URLs were already collected, they were saved to '${autoSavePath}'.\nResume: pin-dl download ${autoSavePath} -o ${Option.getOrElse(opts.output, () => ".")} --skip-existing\n`);
+		else process.stderr.write("\nInterrupted. Re-run the same command with --skip-existing to continue where you left off.\n");
+		process.exit(130);
+	});
+	let urls = [...opts.urls];
+	if (Option.isSome(opts.file)) {
+		const filePath = opts.file.value;
+		urls = [...yield* Effect.tryPromise({
+			try: () => readLines(filePath),
+			catch: (e) => /* @__PURE__ */ new Error(`Failed to read file: ${String(e)}`)
+		}), ...urls];
+	}
+	if (urls.length === 0) {
+		yield* Console.error("Error: No URLs provided. Pass URLs as arguments or use --file.");
+		return;
+	}
+	if (Option.isSome(opts.section)) {
+		const slug = opts.section.value.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
+		urls = urls.map((url) => {
+			return `${url.endsWith("/") ? url : url + "/"}${slug}/`;
+		});
+	}
+	let session;
+	if (Option.isSome(opts.cookies)) {
+		const cookiesPath = opts.cookies.value;
+		const savedCookies = yield* readCookiesFile(cookiesPath);
+		if (!checkCookiesAuthenticated(savedCookies)) yield* Console.log(`[WARNING] Cookies in '${cookiesPath}' are NOT authenticated (_auth != 1). Private boards may fail. Run: pin-dl login -o cookies.json`);
+		session = yield* makeSession(savedCookies);
+	} else session = yield* makeSession();
+	for (const url of urls) yield* processUrl(url, effectiveOpts, session).pipe(Effect.catchAll((e) => Console.error(`Error scraping ${url}: ${e.message ?? String(e)}`)));
+	yield* Console.log("\nDone.");
+}).pipe(Effect.catchAll((e) => Console.error(`Fatal error: ${e.message ?? String(e)}`))));
+
+//#endregion
+//#region src/cli/commands/search.ts
+const searchCommand = Command.make("search", {
+	queries: Args.between(Args.text({ name: "query" }), 0, 999),
+	output: outputOption,
+	file: fileOption,
+	cookies: cookiesOption,
+	num: numOption,
+	resolution: resolutionOption,
+	video: videoOption,
+	skipRemux: skipRemuxOption,
+	reencode: reencodeOption,
+	timeout: timeoutOption,
+	delay: delayOption,
+	cache: cacheOption,
+	caption: captionOption,
+	ensureCap: ensureCapOption,
+	capFromTitle: capFromTitleOption,
+	verbose: verboseOption,
+	dump: dumpOption,
+	logFile: logFileOption,
+	dryRun: dryRunOption,
+	skipExisting: skipExistingOption,
+	filename: filenameOption
+}, (opts) => Effect.gen(function* () {
+	if (Option.isSome(opts.logFile)) setupLogFile(opts.logFile.value);
+	const autoSavePath = Option.isNone(opts.cache) && Option.isSome(opts.output) ? `${opts.output.value}.json` : null;
+	const effectiveCache = autoSavePath !== null ? Option.some(autoSavePath) : opts.cache;
+	process.once("SIGINT", () => {
+		if (autoSavePath) process.stderr.write(`\nInterrupted. If results were already scraped, they were saved to '${autoSavePath}'.\nResume: pin-dl download ${autoSavePath} -o ${Option.getOrElse(opts.output, () => ".")} --skip-existing\n`);
+		else process.stderr.write("\nInterrupted. Re-run the same command with --skip-existing to continue where you left off.\n");
+		process.exit(130);
+	});
+	let queries = [...opts.queries];
+	if (Option.isSome(opts.file)) {
+		const filePath = opts.file.value;
+		queries = [...yield* Effect.tryPromise({
+			try: () => readLines(filePath),
+			catch: (e) => /* @__PURE__ */ new Error(`Failed to read file: ${String(e)}`)
+		}), ...queries];
+	}
+	if (queries.length === 0) {
+		yield* Console.error("Error: No queries provided. Pass queries as arguments or use --file.");
+		return;
+	}
+	let session;
+	if (Option.isSome(opts.cookies)) {
+		const cookiesPath = opts.cookies.value;
+		const savedCookies = yield* readCookiesFile(cookiesPath);
+		if (!checkCookiesAuthenticated(savedCookies)) yield* Console.log(`[WARNING] Cookies in '${cookiesPath}' may not be authenticated.`);
+		session = yield* makeSession(savedCookies);
+	} else session = yield* makeSession();
+	const minRes = Option.isSome(opts.resolution) ? parseResolution(opts.resolution.value) : [0, 0];
+	for (const query of queries) {
+		yield* Console.log(`Searching '${query}'...`);
+		const media = yield* scrapeQuery(session, query, {
+			num: opts.num,
+			minResolution: minRes,
+			delay: parseDelay(opts.delay),
+			captionFromTitle: opts.capFromTitle,
+			ensureAlt: opts.ensureCap,
+			timeout: opts.timeout * 1e3,
+			verbose: opts.verbose,
+			dump: Option.getOrUndefined(opts.dump),
+			onProgress: (collected, total) => {
+				process.stderr.write(`\r  Scraped ${collected}/${total}...`);
+			}
+		}).pipe(Effect.catchAll((e) => {
+			process.stderr.write("\n");
+			Console.error(`Error searching '${query}': ${e.message ?? String(e)}`);
+			return Effect.succeed([]);
+		}));
+		process.stderr.write("\n");
+		if (opts.verbose) for (const m of media) yield* Console.log(`  ${m.src}`);
+		if (opts.dryRun) {
+			for (const m of media) yield* Console.log(m.src);
+			yield* Console.log(`Found ${media.length} item(s).`);
+			if (Option.isSome(effectiveCache)) {
+				yield* writeCacheFile(media, effectiveCache.value);
+				yield* Console.log(`Saved URLs → ${effectiveCache.value}`);
+			}
+			continue;
+		}
+		if (Option.isSome(effectiveCache)) {
+			yield* writeCacheFile(media, effectiveCache.value);
+			yield* Console.log(`Cached ${media.length} items → ${effectiveCache.value}`);
+		}
+		if (Option.isNone(opts.output)) {
+			if (Option.isNone(effectiveCache)) yield* Console.log(JSON.stringify(media.map((m) => ({
+				src: m.src,
+				alt: m.alt,
+				origin: m.origin
+			})), null, 2));
+			continue;
+		}
+		const outputDir = opts.output.value;
+		const downloaded = yield* downloadMedia(media, outputDir, opts.video, opts.skipRemux, opts.reencode, 8, opts.skipExisting, opts.filename);
+		const captionMode = isCaptionMode(opts.caption) ? opts.caption : "none";
+		if (captionMode !== "none") yield* applyCaption(downloaded, outputDir, captionMode);
+		if (downloaded.length !== opts.num) yield* Console.log(`Note: Got ${downloaded.length} items (requested ${opts.num}).`);
+	}
+	yield* Console.log("\nDone.");
+}).pipe(Effect.catchAll((e) => Console.error(`Fatal error: ${e.message ?? String(e)}`))));
+
+//#endregion
+//#region src/cli/commands/download.ts
+const downloadCommand = Command.make("download", {
+	input: Args.text({ name: "input" }),
+	output: outputOption,
+	resolution: resolutionOption,
+	video: videoOption,
+	skipRemux: skipRemuxOption,
+	reencode: reencodeOption,
+	caption: captionOption,
+	ensureCap: ensureCapOption,
+	verbose: verboseOption,
+	logFile: logFileOption,
+	skipExisting: skipExistingOption,
+	filename: filenameOption
+}, (opts) => Effect.gen(function* () {
+	if (Option.isSome(opts.logFile)) setupLogFile(opts.logFile.value);
+	if (opts.input.startsWith("http://") || opts.input.startsWith("https://")) {
+		yield* Console.error(`Error: 'download' expects a saved URLs file (from --save-urls), not a URL.
+To scrape and download directly, run:
+  pin-dl ${opts.input} -o <dir>`);
+		return;
+	}
+	let media = yield* readCacheFile(opts.input);
+	if (Option.isSome(opts.resolution)) {
+		const [minW, minH] = parseResolution(opts.resolution.value);
+		media = media.filter((m) => (m.resolution.x ?? 0) >= minW && (m.resolution.y ?? 0) >= minH);
+	}
+	if (opts.ensureCap) media = filterWithAlt(media);
+	const outputDir = Option.getOrElse(opts.output, () => path.basename(opts.input, path.extname(opts.input)));
+	yield* Console.log(`Downloading ${media.length} items to '${outputDir}'...`);
+	const downloaded = yield* downloadMedia(media, outputDir, opts.video, opts.skipRemux, opts.reencode, 8, opts.skipExisting, opts.filename);
+	const captionMode = isCaptionMode(opts.caption) ? opts.caption : "none";
+	if (captionMode !== "none") yield* applyCaption(downloaded, outputDir, captionMode);
+	if (opts.verbose) {
+		for (const m of downloaded) if (m.localPath) yield* Console.log(`  ${m.localPath}`);
+	}
+	yield* Console.log(`\nDownloaded ${downloaded.length} items.\nDone.`);
+}).pipe(Effect.catchAll((e) => Console.error(`Error: ${e.message ?? String(e)}`))));
+
+//#endregion
+//#region src/cli/dispatch.ts
+const knownSubcommands = new Set([
+	"login",
+	"scrape",
+	"search",
+	"download"
+]);
+/**
+* Normalise raw argv before subcommand dispatch.
+* - `--stdin`              → `--file -`
+* - `--resume`/`--continue`  → `--skip-existing`
+* - first arg `get`        → `scrape`
+* - first arg `similar`    → `scrape --related`
+* Returns a new array; does not mutate the input.
+*/
+const preprocessArgv = (args) => {
+	let result = [...args];
+	const stdinIdx = result.indexOf("--stdin");
+	if (stdinIdx !== -1) result = [
+		...result.slice(0, stdinIdx),
+		"--file",
+		"-",
+		...result.slice(stdinIdx + 1)
+	];
+	result = result.map((a) => a === "--resume" || a === "--continue" ? "--skip-existing" : a);
+	if (result[0] === "get") result = ["scrape", ...result.slice(1)];
+	if (result[0] === "similar") result = [
+		"scrape",
+		"--related",
+		...result.slice(1)
+	];
+	return result;
+};
+/**
+* Given raw args (after preprocessing), return the subcommand to inject
+* ("scrape" | "search") or null if a subcommand is already present or no
+* positional args exist.
+*/
+const resolveDispatch = (args, subcommands = knownSubcommands) => {
+	if (args.some((a) => subcommands.has(a))) return null;
+	if (args.some((a) => a.startsWith("https://") || a.startsWith("http://")) || args.some((a) => a === "-f" || a === "--file")) return "scrape";
+	const first = args[0];
+	if (first !== void 0 && !first.startsWith("-") && !subcommands.has(first)) return "search";
+	return null;
+};
+
+//#endregion
+//#region src/index.ts
+const preprocessed = preprocessArgv(process.argv.slice(2));
+if (preprocessed.length !== process.argv.slice(2).length || preprocessed.some((v, i) => v !== process.argv.slice(2)[i])) process.argv = [...process.argv.slice(0, 2), ...preprocessed];
+const rawArgs = process.argv.slice(2);
+const dispatched = resolveDispatch(rawArgs);
+if (dispatched === "search") {
+	const splitAt = rawArgs.findIndex((a) => a.startsWith("-")) === -1 ? rawArgs.length : rawArgs.findIndex((a) => a.startsWith("-"));
+	const query = rawArgs.slice(0, splitAt).join(" ");
+	const rest = rawArgs.slice(splitAt);
+	process.argv = [
+		...process.argv.slice(0, 2),
+		"search",
+		query,
+		...rest
+	];
+} else if (dispatched === "scrape") process.argv = [
+	...process.argv.slice(0, 2),
+	"scrape",
+	...rawArgs
+];
+const root = Command.make("pin-dl").pipe(Command.withSubcommands([
+	loginCommand,
+	scrapeCommand,
+	searchCommand,
+	downloadCommand
+]));
+const cli = Command.run(root, {
+	name: "pin-dl",
+	version: "0.1.0"
+});
+NodeRuntime.runMain(Effect.suspend(() => cli(process.argv)).pipe(Effect.provide(NodeContext.layer)));
+
+//#endregion
+export {  };