@mrclrchtr/supi-web 7.1.0 → 7.2.0

package/src/settings-registration.ts

@@ -0,0 +1,63 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  defineConfigSettings,
+  registerSettings,
+  type SettingsModule,
+} from "@mrclrchtr/supi-core/settings";
+import {
+  loadWebConfig,
+  WEB_CONFIG_SECTION,
+  WEB_DEFAULTS,
+  WEB_SEARCH_ENABLED_KEY,
+} from "./config.ts";
+import { isBxAvailable } from "./tool/web_search/bx.ts";
+
+const RELOAD_NOTICE = "Web Search setting saved. Run /reload to apply this change.";
+
+/** Register the Web Search setting without changing active tools. */
+export function registerWebSettings(pi: ExtensionAPI, homeDir?: string): void {
+  const fixedSettings = defineConfigSettings({
+    id: WEB_CONFIG_SECTION,
+    label: "Web Search",
+    section: WEB_CONFIG_SECTION,
+    defaults: WEB_DEFAULTS,
+    fields: [
+      {
+        kind: "boolean" as const,
+        key: WEB_SEARCH_ENABLED_KEY,
+        label: "Web Search tool",
+        description: "Enable the web_search tool when bx is available on PATH",
+      },
+    ],
+    ...(homeDir ? { homeDir } : {}),
+  });
+
+  const settings: SettingsModule = {
+    ...fixedSettings,
+    apply: async (request) => {
+      const result = await fixedSettings.apply(request);
+      if (
+        request.fieldKey === WEB_SEARCH_ENABLED_KEY &&
+        loadWebConfig(request.cwd, homeDir).webSearchEnabled &&
+        !isBxAvailable()
+      ) {
+        return {
+          notice: {
+            message: `${RELOAD_NOTICE} bx is not available on PATH, so web_search will stay unavailable until bx is available.`,
+            level: "warning",
+          },
+        };
+      }
+
+      return {
+        ...result,
+        notice: {
+          message: RELOAD_NOTICE,
+          level: "info",
+        },
+      };
+    },
+  };
+
+  registerSettings(pi, settings);
+}

package/src/tool/tool-specs.ts

@@ -32,6 +32,16 @@ import {
   WEB_FETCH_MD_TOOL_NAME,
   webFetchMdParameters,
 } from "./web_fetch_md/spec.ts";
+import {
+  toolDescription as webSearchDescription,
+  promptGuidelines as webSearchGuidelines,
+  promptSnippet as webSearchSnippet,
+} from "./web_search/guidance.ts";
+import {
+  WEB_SEARCH_TOOL_LABEL,
+  WEB_SEARCH_TOOL_NAME,
+  webSearchParameters,
+} from "./web_search/spec.ts";
 
 export type { WebDocsFetchInput } from "./web_docs_fetch/spec.ts";
 export { WEB_DOCS_FETCH_TOOL_NAME } from "./web_docs_fetch/spec.ts";
@@ -39,11 +49,14 @@ export type { WebDocsSearchInput } from "./web_docs_search/spec.ts";
 export { WEB_DOCS_SEARCH_TOOL_NAME } from "./web_docs_search/spec.ts";
 export type { WebFetchMdInput, WebFetchOutputMode } from "./web_fetch_md/spec.ts";
 export { WEB_FETCH_INLINE_MAX_CHARS, WEB_FETCH_MD_TOOL_NAME } from "./web_fetch_md/spec.ts";
+export type { WebSearchInput } from "./web_search/spec.ts";
+export { WEB_SEARCH_TOOL_NAME } from "./web_search/spec.ts";
 
 export const WEB_TOOL_NAMES = [
   WEB_FETCH_MD_TOOL_NAME,
   WEB_DOCS_SEARCH_TOOL_NAME,
   WEB_DOCS_FETCH_TOOL_NAME,
+  WEB_SEARCH_TOOL_NAME,
 ] as const;
 export type WebToolName = (typeof WEB_TOOL_NAMES)[number];
 
@@ -88,6 +101,14 @@ export const WEB_TOOL_SPECS = [
     promptGuidelines: docsFetchGuidelines,
     parameters: webDocsFetchParameters,
   },
+  {
+    name: WEB_SEARCH_TOOL_NAME,
+    label: WEB_SEARCH_TOOL_LABEL,
+    description: webSearchDescription,
+    promptSnippet: webSearchSnippet,
+    promptGuidelines: webSearchGuidelines,
+    parameters: webSearchParameters,
+  },
 ] as const satisfies readonly WebToolSpec[];
 
 export function getWebToolSpec(name: WebToolName): WebToolSpec {

package/src/tool/web_search/bx.ts

@@ -0,0 +1,178 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+
+interface BxRunOptions {
+  cwd: string;
+  signal?: AbortSignal;
+}
+
+interface BxProcessResult {
+  stdout: string;
+  exitCode: number | null;
+}
+
+type BxFailureKind = "cancelled" | "missing" | "start";
+
+/** Return a safe message for a documented bx process exit category. */
+export function formatBxExitFailure(exitCode: number | null): string {
+  switch (exitCode) {
+    case 1:
+      return "bx web search failed: client error. Check the query and request.";
+    case 2:
+      return "bx web search failed: CLI usage or compatibility error. Check the bx version.";
+    case 3:
+      return "bx web search failed: authentication or permission error. Check bx credentials and service access.";
+    case 4:
+      return "bx web search failed: rate limit reached. Try again later.";
+    case 5:
+      return "bx web search failed: server or network error. Check network access and try again later.";
+    default:
+      return `bx web search failed: unknown bx error (exit code ${exitCode ?? "unknown"}).`;
+  }
+}
+
+class BxProcessFailure extends Error {
+  constructor(readonly kind: BxFailureKind) {
+    super(kind);
+  }
+}
+
+/** Build the direct argv used for one bx context request. */
+export function buildBxContextArgs(query: string, freshness?: string): string[] {
+  return [
+    "context",
+    ...(freshness === undefined ? [] : ["--extra", `freshness=${freshness}`]),
+    "--",
+    query,
+  ];
+}
+
+/** Check PATH without starting bx or reading its configuration. */
+export function isBxAvailable(
+  pathValue = process.env.PATH,
+  platform = process.platform,
+  pathExtValue = process.env.PATHEXT,
+): boolean {
+  if (!pathValue) return false;
+
+  const names = platform === "win32" ? windowsCommandNames(pathExtValue) : ["bx"];
+  const pathDelimiter = platform === "win32" ? ";" : delimiter;
+  return pathValue
+    .split(pathDelimiter)
+    .some((directory) =>
+      names.some((name) => isExecutable(join(directory || ".", name), platform)),
+    );
+}
+
+/** Run one bx context request and decode its JSON stdout. */
+export async function runBxContext(
+  query: string,
+  freshness: string | undefined,
+  options: BxRunOptions,
+): Promise<unknown> {
+  const result = await invokeBx(buildBxContextArgs(query, freshness), options);
+  if (result.exitCode !== 0) {
+    throw new Error(formatBxExitFailure(result.exitCode));
+  }
+
+  try {
+    return JSON.parse(result.stdout) as unknown;
+  } catch {
+    // biome-ignore lint/style/useErrorCause: Keep parser details out of tool errors.
+    throw new Error("bx returned invalid JSON for web search.");
+  }
+}
+
+function windowsCommandNames(pathExtValue: string | undefined): string[] {
+  const extensions = (pathExtValue ?? ".COM;.EXE;.BAT;.CMD")
+    .split(";")
+    .map((extension) => extension.trim())
+    .filter(Boolean);
+  return ["bx", ...extensions.map((extension) => `bx${extension}`)];
+}
+
+function isExecutable(filePath: string, platform: NodeJS.Platform): boolean {
+  try {
+    if (!statSync(filePath).isFile()) return false;
+    accessSync(filePath, platform === "win32" ? constants.F_OK : constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function invokeBx(args: string[], options: BxRunOptions): Promise<BxProcessResult> {
+  if (options.signal?.aborted) throw new Error("Web search was cancelled.");
+
+  return new Promise<BxProcessResult>((resolve, reject) => {
+    const decoder = new StringDecoder("utf8");
+    let stdout = "";
+    let settled = false;
+    let cancelled = false;
+    let child: ReturnType<typeof spawn>;
+
+    try {
+      child = spawn("bx", args, {
+        cwd: options.cwd,
+        shell: false,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch {
+      reject(new BxProcessFailure("start"));
+      return;
+    }
+
+    const cleanup = () => {
+      options.signal?.removeEventListener("abort", onAbort);
+    };
+    const finish = (callback: () => void) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      callback();
+    };
+    const onAbort = () => {
+      cancelled = true;
+      try {
+        child.kill();
+      } catch {
+        // The process may have already exited.
+      }
+      finish(() => reject(new BxProcessFailure("cancelled")));
+    };
+
+    child.stdout?.on("data", (chunk: Buffer | string) => {
+      stdout += typeof chunk === "string" ? chunk : decoder.write(chunk);
+    });
+    child.stderr?.on("data", () => {
+      // Drain stderr. Its contents must not enter model-visible errors.
+    });
+    child.once("error", (error: NodeJS.ErrnoException) => {
+      finish(() => {
+        if (cancelled) {
+          reject(new BxProcessFailure("cancelled"));
+        } else if (error.code === "ENOENT") {
+          reject(new BxProcessFailure("missing"));
+        } else {
+          reject(new BxProcessFailure("start"));
+        }
+      });
+    });
+    child.once("close", (exitCode: number | null) => {
+      finish(() => resolve({ stdout: `${stdout}${decoder.end()}`, exitCode }));
+    });
+
+    if (options.signal) {
+      options.signal.addEventListener("abort", onAbort, { once: true });
+    }
+  }).catch((error: unknown): BxProcessResult => {
+    if (error instanceof BxProcessFailure) {
+      if (error.kind === "cancelled") throw new Error("Web search was cancelled.");
+      if (error.kind === "missing") throw new Error("bx executable was not found on PATH.");
+      throw new Error("Could not start bx for web search.");
+    }
+    throw new Error("Could not start bx for web search.");
+  });
+}

package/src/tool/web_search/execute.ts

@@ -0,0 +1,39 @@
+import type {
+  AgentToolResult,
+  AgentToolUpdateCallback,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { limitModelVisibleOutput } from "../result.ts";
+import { runBxContext } from "./bx.ts";
+import { validateWebSearchInput } from "./input.ts";
+import { parseBxResponse } from "./parse.ts";
+import { buildSearchResult, formatSearchResults, type WebSearchDetails } from "./result.ts";
+
+/** Execute one direct bx context search. */
+// biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
+export async function runWebSearch(
+  _toolCallId: string,
+  params: unknown,
+  signal: AbortSignal | undefined,
+  onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined,
+  ctx: ExtensionContext,
+): Promise<AgentToolResult<WebSearchDetails>> {
+  const input = validateWebSearchInput(params);
+  onUpdate?.({
+    content: [{ type: "text", text: "Searching the web..." }],
+    details: { status: "searching" },
+  });
+
+  const payload = await runBxContext(input.query, input.freshness, {
+    cwd: ctx.cwd,
+    ...(signal ? { signal } : {}),
+  });
+  const parsed = parseBxResponse(payload);
+  const markdown = formatSearchResults(parsed.sources);
+  const output = await limitModelVisibleOutput(markdown, {
+    tempPrefix: "web-search",
+    suffix: ".md",
+  });
+
+  return buildSearchResult(parsed.sources, output);
+}

package/src/tool/web_search/guidance.ts

@@ -0,0 +1,6 @@
+export const toolDescription =
+  "Search the public web and return source titles, URLs, and source excerpts for current or external information. It does not generate an answer.";
+
+export const promptSnippet = "search public web sources";
+
+export const promptGuidelines = ["Use web_search when current or external web sources are needed."];

package/src/tool/web_search/input.ts

@@ -0,0 +1,91 @@
+import type { Static } from "typebox";
+import { Type } from "typebox";
+
+/** Short freshness filters accepted by the Brave context service. */
+export const WEB_SEARCH_FRESHNESS_CODES = ["pd", "pw", "pm", "py"] as const;
+
+/** Parameter schema for web_search. */
+export const webSearchParameters = Type.Object(
+  {
+    query: Type.String({
+      minLength: 1,
+      description: "Search terms or a question for the public web",
+    }),
+    freshness: Type.Optional(
+      Type.String({
+        minLength: 1,
+        description:
+          "Freshness filter: pd (24 hours), pw (7 days), pm (31 days), py (365 days), or an ordered YYYY-MM-DDtoYYYY-MM-DD range. Brave uses the page publication or modification date.",
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+/** Input type for web_search. */
+export type WebSearchInput = Static<typeof webSearchParameters>;
+
+/** Input after runtime validation. */
+export interface ValidWebSearchInput {
+  query: string;
+  freshness?: string;
+}
+
+/** Validate tool input used by direct callers as well as Pi. */
+export function validateWebSearchInput(params: unknown): ValidWebSearchInput {
+  if (!isRecord(params)) throw new Error("web_search input must be an object");
+
+  const query = typeof params.query === "string" ? params.query.trim() : "";
+  if (!query) throw new Error("'query' parameter is required");
+
+  const freshness = params.freshness;
+  if (freshness !== undefined) {
+    if (typeof freshness !== "string" || !isValidFreshness(freshness)) {
+      throw new Error(
+        "'freshness' must be pd, pw, pm, py, or an ordered YYYY-MM-DDtoYYYY-MM-DD range",
+      );
+    }
+  }
+
+  return { query, ...(freshness === undefined ? {} : { freshness }) };
+}
+
+/** Return whether a freshness value is documented and valid. */
+export function isValidFreshness(value: string): boolean {
+  if ((WEB_SEARCH_FRESHNESS_CODES as readonly string[]).includes(value)) return true;
+
+  const match = /^(\d{4})-(\d{2})-(\d{2})to(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) return false;
+
+  const [, startYear, startMonth, startDay, endYear, endMonth, endDay] = match;
+  if (
+    !isValidIsoDate(`${startYear}-${startMonth}-${startDay}`) ||
+    !isValidIsoDate(`${endYear}-${endMonth}-${endDay}`)
+  ) {
+    return false;
+  }
+
+  return value.slice(0, 10) <= value.slice(12);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Return whether a value is a real ISO calendar date. */
+export function isValidIsoDate(value: string): boolean {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) return false;
+
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  if (year < 1 || month < 1 || month > 12 || day < 1) return false;
+
+  const daysInMonth = [31, isLeapYear(year) ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return day <= (daysInMonth[month - 1] ?? 0);
+}
+
+function isLeapYear(year: number): boolean {
+  return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+}

package/src/tool/web_search/parse.ts

@@ -0,0 +1,92 @@
+import { isValidIsoDate } from "./input.ts";
+
+/** One source returned by the Web Search context response. */
+export interface WebSearchSource {
+  title: string;
+  url: string;
+  excerpts: string[];
+  sourceDate?: string;
+}
+
+/** Parsed source data used by the Web Search result assembler. */
+export interface ParsedWebSearchResponse {
+  sources: WebSearchSource[];
+}
+
+/** Validate the required bx response envelope and keep only source data. */
+export function parseBxResponse(payload: unknown): ParsedWebSearchResponse {
+  const root = asRecord(payload);
+  const grounding = asRecord(root?.grounding);
+  if (!grounding || !Array.isArray(grounding.generic)) {
+    throw new Error("bx returned malformed web search data: grounding.generic is required.");
+  }
+
+  const sources = grounding.generic.map((value, index) =>
+    parseSource(value, index, findSourceDate(root, value)),
+  );
+  return { sources };
+}
+
+function parseSource(
+  value: unknown,
+  index: number,
+  sourceDate: string | undefined,
+): WebSearchSource {
+  const source = asRecord(value);
+  if (!source) throw new Error(`bx returned malformed web search source at index ${index}.`);
+
+  const title = requiredText(source.title, "title", index);
+  const url = requiredText(source.url, "url", index);
+  if (!Array.isArray(source.snippets)) {
+    throw new Error(
+      `bx returned malformed web search source at index ${index}: snippets is required.`,
+    );
+  }
+
+  return {
+    title,
+    url,
+    excerpts: source.snippets.map((snippet, snippetIndex) =>
+      parseSnippet(snippet, index, snippetIndex),
+    ),
+    ...(sourceDate ? { sourceDate } : {}),
+  };
+}
+
+function requiredText(value: unknown, field: string, index: number): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(
+      `bx returned malformed web search source at index ${index}: ${field} is required.`,
+    );
+  }
+  return value.trim();
+}
+
+function parseSnippet(value: unknown, sourceIndex: number, snippetIndex: number): string {
+  if (typeof value === "string") return value;
+
+  throw new Error(
+    `bx returned malformed web search snippet at source ${sourceIndex}, index ${snippetIndex}.`,
+  );
+}
+
+function findSourceDate(root: Record<string, unknown> | null, source: unknown): string | undefined {
+  const sourceRecord = asRecord(source);
+  const url = typeof sourceRecord?.url === "string" ? sourceRecord.url : undefined;
+  const sources = asRecord(root?.sources);
+  const metadata = url ? asRecord(sources?.[url]) : null;
+  return findSafeDate(metadata?.age);
+}
+
+function findSafeDate(value: unknown): string | undefined {
+  if (typeof value === "string") return isValidIsoDate(value) ? value : undefined;
+  if (!Array.isArray(value)) return undefined;
+
+  return value.find((item): item is string => typeof item === "string" && isValidIsoDate(item));
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}

package/src/tool/web_search/register.ts

@@ -0,0 +1,16 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { promptGuidelines, promptSnippet, toolDescription } from "./guidance.ts";
+import { renderWebSearchCall, renderWebSearchResult } from "./render.ts";
+import { webSearchSpec } from "./spec.ts";
+
+/** Register the web_search tool. */
+export function registerWebSearchTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    ...webSearchSpec,
+    description: toolDescription,
+    promptSnippet,
+    promptGuidelines: [...promptGuidelines],
+    renderCall: renderWebSearchCall,
+    renderResult: renderWebSearchResult,
+  });
+}

package/src/tool/web_search/render.ts

@@ -0,0 +1,95 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { renderCollapsibleTextResult, renderToolCall } from "../render.ts";
+import { WEB_SEARCH_TOOL_NAME, type WebSearchInput } from "./spec.ts";
+
+/** Transcript renderer for web_search tool calls. */
+export function renderWebSearchCall(args: unknown, theme: Theme) {
+  const input = (args ?? {}) as Partial<WebSearchInput>;
+  const query = typeof input.query === "string" ? truncatePreview(input.query) : "";
+  const freshness = typeof input.freshness === "string" ? input.freshness : undefined;
+  return renderToolCall(WEB_SEARCH_TOOL_NAME, query, theme, freshness);
+}
+
+/** Transcript renderer for web_search tool results. */
+export function renderWebSearchResult(
+  result: { content: Array<{ type: string; text?: string }>; details?: unknown },
+  { expanded, isPartial }: { expanded: boolean; isPartial: boolean },
+  theme: Theme,
+  context: { isError?: boolean } = {},
+) {
+  if (isPartial) {
+    return renderCollapsibleTextResult({
+      summary: theme.fg("warning", "Searching the web..."),
+      expanded,
+      theme,
+    });
+  }
+
+  if (context.isError) {
+    return renderCollapsibleTextResult({
+      summary: theme.fg("error", "Web search failed"),
+      expanded,
+      theme,
+    });
+  }
+
+  const details = readSearchDetails(result.details);
+  const summary = buildSearchSummary(details, theme);
+  const content = result.content.find((item) => item.type === "text");
+  const body =
+    details?.sourceCount === 0 ? undefined : content?.type === "text" ? content.text : undefined;
+
+  return renderCollapsibleTextResult({
+    summary,
+    body,
+    expanded,
+    theme,
+    fullOutputPath: details?.fullOutputPath,
+  });
+}
+
+function truncatePreview(text: string, maxChars = 48): string {
+  const compact = text.replace(/\s+/g, " ").trim();
+  if (compact.length <= maxChars) return compact;
+  return `${compact.slice(0, maxChars - 1).trimEnd()}…`;
+}
+
+interface RenderSearchDetails {
+  sourceCount: number;
+  truncated: boolean;
+  fullOutputPath?: string;
+}
+
+function readSearchDetails(value: unknown): RenderSearchDetails | undefined {
+  if (!isRecord(value)) return undefined;
+  const sourceCount = value.sourceCount;
+  if (typeof sourceCount !== "number" || !Number.isInteger(sourceCount) || sourceCount < 0) {
+    return undefined;
+  }
+
+  const truncation = isRecord(value.truncation) ? value.truncation : undefined;
+  const fullOutputPath = value.fullOutputPath;
+  return {
+    sourceCount,
+    truncated: truncation?.truncated === true,
+    ...(typeof fullOutputPath === "string" && fullOutputPath.length > 0 ? { fullOutputPath } : {}),
+  };
+}
+
+function buildSearchSummary(
+  details: RenderSearchDetails | undefined,
+  theme: { fg: (color: "success" | "warning" | "dim", text: string) => string },
+): string {
+  if (!details) return theme.fg("success", "Web search finished");
+
+  if (details.sourceCount === 0) return theme.fg("warning", "No web search sources found");
+
+  const noun = details.sourceCount === 1 ? "source" : "sources";
+  let summary = theme.fg("success", `Found ${details.sourceCount} ${noun}`);
+  if (details.truncated) summary += theme.fg("warning", " [truncated]");
+  return summary;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/tool/web_search/result.ts

@@ -0,0 +1,58 @@
+import type { AgentToolResult, TruncationResult } from "@earendil-works/pi-coding-agent";
+import type { ModelVisibleOutput } from "../result.ts";
+import type { WebSearchSource } from "./parse.ts";
+
+/** Human-facing and model-facing facts for one Web Search result. */
+export interface WebSearchDetails extends Record<string, unknown> {
+  sourceCount: number;
+  excerptCount: number;
+  truncation?: TruncationResult;
+  fullOutputPath?: string;
+}
+
+/** Assemble a successful Web Search result. */
+export function buildSearchResult(
+  sources: WebSearchSource[],
+  output: ModelVisibleOutput,
+): AgentToolResult<WebSearchDetails> {
+  return {
+    content: [{ type: "text", text: output.text }],
+    details: {
+      sourceCount: sources.length,
+      excerptCount: sources.reduce((count, source) => count + source.excerpts.length, 0),
+      truncation: output.truncation,
+      fullOutputPath: output.fullOutputPath,
+    },
+  };
+}
+
+/** Format all provider sources and excerpts as compact Markdown. */
+export function formatSearchResults(sources: WebSearchSource[]): string {
+  if (sources.length === 0) return "No web search sources found.";
+
+  const lines = ["Source excerpts. Dates are provider-reported publication or modification dates."];
+  for (const source of sources) {
+    lines.push("", `### [${escapeLinkText(source.title)}](<${escapeUrl(source.url)}>)`);
+    if (source.sourceDate) lines.push(`Source date: ${source.sourceDate}`);
+    for (const excerpt of source.excerpts) lines.push("", formatExcerpt(excerpt));
+  }
+
+  return lines.join("\n");
+}
+
+function formatExcerpt(excerpt: string): string {
+  const lines = excerpt.split(/\r?\n/);
+  return lines.map((line) => `> ${line}`).join("\n");
+}
+
+function escapeLinkText(value: string): string {
+  return value
+    .replace(/\\/g, "\\\\")
+    .replace(/\[/g, "\\[")
+    .replace(/\]/g, "\\]")
+    .replace(/\r?\n/g, " ");
+}
+
+function escapeUrl(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/>/g, "\\>").replace(/\r?\n/g, "");
+}