/**
 * Pure formatters for the web_search tool — input → output, no I/O.
 *
 * These mirror the proven opencode Firecrawl tool's formatting, isolated
 * (not imported) per the isolation-over-DRY rule. Tested directly with
 * zero mocks.
 */

/** A single search hit from Firecrawl's `/search` endpoint. */
export interface SearchHit {
	readonly title?: string;
	readonly url?: string;
	readonly description?: string;
	readonly markdown?: string;
}

/** One page from a completed crawl (`/crawl` status `data`). */
export interface CrawlPage {
	readonly markdown?: string;
	readonly metadata?: {
		readonly title?: string;
		readonly sourceURL?: string;
		readonly url?: string;
	};
}

/** The scrape response payload (`/scrape` `data`). */
export interface ScrapeResult {
	readonly data?: {
		readonly markdown?: string;
		readonly metadata?: { readonly title?: string };
	};
}

/**
 * Truncate output to `cap` characters with a trailing notice, identical in
 * spirit to tool-shell. Duplication across features is the intended trade.
 */
export function truncateOutput(output: string, cap: number): string {
	if (output.length <= cap) {
		return output;
	}
	const truncated = output.slice(0, cap);
	return `${truncated}\n\n[Output truncated: exceeded ${cap} characters]`;
}

/**
 * Format search hits as `### title\nurl\n\ndescription` (+ optional markdown),
 * joined by `---` separators. Empty → `"No results found."`.
 */
export function formatSearchResults(data: readonly SearchHit[] | null | undefined): string {
	if (!data || data.length === 0) {
		return "No results found.";
	}
	const parts: string[] = [];
	for (const r of data) {
		const title = r.title ?? "(no title)";
		const url = r.url ?? "";
		const description = r.description ?? "";
		let section = `### ${title}\n${url}\n\n${description}`;
		if (r.markdown) {
			section += `\n\n${r.markdown}`;
		}
		parts.push(section);
	}
	return parts.join("\n\n---\n\n");
}

/**
 * Format a scrape response as `# title\n\nmarkdown`, omitting the header when
 * the title is absent.
 */
export function formatScrapeResult(json: ScrapeResult): string {
	const md = json.data?.markdown ?? "";
	const title = json.data?.metadata?.title;
	if (title) {
		return `# ${title}\n\n${md}`;
	}
	return md;
}

/**
 * Format crawled pages as `## title\nurl\n\nmarkdown` each, joined by `---`.
 * Empty → `"No pages crawled."`.
 */
export function formatCrawlResults(data: readonly CrawlPage[] | null | undefined): string {
	if (!data || data.length === 0) {
		return "No pages crawled.";
	}
	const parts: string[] = [];
	for (const page of data) {
		const title = page.metadata?.title ?? "(no title)";
		const url = page.metadata?.sourceURL ?? page.metadata?.url ?? "";
		let section = `## ${title}\n${url}`;
		if (page.markdown) {
			section += `\n\n${page.markdown}`;
		}
		parts.push(section);
	}
	return parts.join("\n\n---\n\n");
}

/**
 * Format discovered links as a bullet list. Empty → `"No links found."`.
 */
export function formatMapResults(links: readonly string[] | null | undefined): string {
	if (!links || links.length === 0) {
		return "No links found.";
	}
	return links.map((l) => `- ${l}`).join("\n");
}