@hraness/kb 0.17.1

package/src/clip/refresh.ts

@@ -0,0 +1,197 @@
+import { createHash } from "node:crypto";
+import { lstat, realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+import { runGitCommand, type GitCommandProvider, type GitCommandResult } from "../git.js";
+import {
+  readCaptureBundle,
+  type CaptureBundleInspection,
+  type ReadCaptureBundleOptions,
+} from "./bundle-reader.js";
+
+const MAX_GIT_DOCUMENT_BYTES = 64 * 1_024 * 1_024;
+const MAX_DIFF_BYTES = 2 * 1_024 * 1_024;
+const GIT_TIMEOUT_MS = 10_000;
+const REF_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,255}$/u;
+const OBJECT_ID_PATTERN = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/u;
+
+export type CaptureBundleDiff = {
+  readonly status: "changed" | "missing-at-ref" | "unchanged";
+  readonly ref: string;
+  readonly repositoryPath: string;
+  readonly currentSha256: string;
+  readonly referenceSha256: string | null;
+  readonly diff: string | null;
+};
+
+export type CaptureBundleDiffOptions = {
+  readonly bundle: string;
+  readonly repository: string;
+  readonly ref?: string;
+  readonly readOptions?: Pick<ReadCaptureBundleOptions, "maxDocumentBytes">;
+};
+
+export type CaptureBundleDiffDependencies = {
+  readonly runGit?: GitCommandProvider;
+  readonly readBundle?: typeof readCaptureBundle;
+};
+
+function gitRef(value: string | undefined): string {
+  const ref = value ?? "HEAD";
+  if (
+    !REF_PATTERN.test(ref)
+    || ref.includes("..")
+    || ref.includes("//")
+    || ref.endsWith("/")
+    || ref.endsWith(".lock")
+  ) throw new TypeError("capture diff ref is not a bounded Git revision name");
+  return ref;
+}
+
+function utf8(value: string | Uint8Array | undefined): Buffer {
+  if (value === undefined) return Buffer.alloc(0);
+  return typeof value === "string" ? Buffer.from(value, "utf8") : Buffer.from(value);
+}
+
+function sha256(value: Uint8Array): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function gitMessage(result: Exclude<GitCommandResult, { readonly status: "ok" }>, label: string): Error {
+  return new Error(`${label}: ${result.message}`);
+}
+
+async function canonicalRepository(input: string): Promise<string> {
+  const repository = await realpath(resolve(input));
+  const stats = await lstat(repository);
+  if (!stats.isDirectory() || stats.isSymbolicLink()) throw new Error("capture diff repository must be a real directory");
+  return repository;
+}
+
+function repositoryPath(repository: string, path: string): string {
+  const fromRepository = relative(repository, path);
+  if (
+    fromRepository === ""
+    || fromRepository === ".."
+    || fromRepository.startsWith(`..${sep}`)
+    || isAbsolute(fromRepository)
+  ) throw new Error("capture bundle must be inside the selected repository");
+  return fromRepository.split(sep).join("/");
+}
+
+async function assertCaptureBundleStable(
+  options: CaptureBundleDiffOptions,
+  readBundle: typeof readCaptureBundle,
+  inspection: CaptureBundleInspection,
+): Promise<void> {
+  const confirmed = await readBundle(options.bundle, options.readOptions);
+  if (
+    confirmed.root !== inspection.root
+    || confirmed.document.path !== inspection.document.path
+    || confirmed.document.sha256 !== inspection.document.sha256
+  ) {
+    throw new Error("Capture bundle changed while its Git comparison was generated; retry.");
+  }
+}
+
+/** Compare one verified stored capture with its exact bytes at a bounded Git ref. */
+export async function diffCaptureBundle(
+  options: CaptureBundleDiffOptions,
+  dependencies: CaptureBundleDiffDependencies = {},
+): Promise<CaptureBundleDiff> {
+  const ref = gitRef(options.ref);
+  const selectedDirectory = await canonicalRepository(options.repository);
+  const readBundle = dependencies.readBundle ?? readCaptureBundle;
+  const inspection = await readBundle(options.bundle, options.readOptions);
+  const runGit = dependencies.runGit ?? runGitCommand;
+  const repositoryCheck = await runGit({
+    arguments: ["rev-parse", "--show-toplevel"],
+    cwd: selectedDirectory,
+    timeoutMs: GIT_TIMEOUT_MS,
+    maxOutputBytes: 4 * 1_024,
+  });
+  if (repositoryCheck.status !== "ok") {
+    throw gitMessage(repositoryCheck, "Capture diff repository is not a Git work tree");
+  }
+  const topLevel = utf8(repositoryCheck.stdout).toString("utf8").trim();
+  if (!isAbsolute(topLevel)) throw new Error("Capture diff repository did not resolve to a canonical Git work tree");
+  const repository = await canonicalRepository(topLevel);
+  const selectedFromRepository = relative(repository, selectedDirectory);
+  if (
+    selectedFromRepository === ".."
+    || selectedFromRepository.startsWith(`..${sep}`)
+    || isAbsolute(selectedFromRepository)
+  ) {
+    throw new Error("Capture diff repository did not resolve inside its Git work tree");
+  }
+  const path = repositoryPath(repository, resolve(inspection.root, inspection.document.path));
+  const refCheck = await runGit({
+    arguments: ["rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`],
+    cwd: repository,
+    timeoutMs: GIT_TIMEOUT_MS,
+    maxOutputBytes: 4 * 1_024,
+  });
+  if (refCheck.status !== "ok") throw gitMessage(refCheck, "Could not resolve capture diff Git ref");
+  const objectId = utf8(refCheck.stdout).toString("utf8").trim();
+  if (!OBJECT_ID_PATTERN.test(objectId)) {
+    throw new Error("Could not resolve capture diff Git ref: Git returned a malformed commit object ID");
+  }
+  const literalPathspec = `:(literal)${path}`;
+  const specifier = `${objectId}:${path}`;
+  const tree = await runGit({
+    arguments: ["ls-tree", "-z", objectId, "--", literalPathspec],
+    cwd: repository,
+    timeoutMs: GIT_TIMEOUT_MS,
+    maxOutputBytes: 8 * 1_024,
+  });
+  if (tree.status !== "ok") throw gitMessage(tree, "Could not inspect capture path at the requested Git ref");
+  if (utf8(tree.stdout).byteLength === 0) {
+    await assertCaptureBundleStable(options, readBundle, inspection);
+    return Object.freeze({
+      status: "missing-at-ref",
+      ref,
+      repositoryPath: path,
+      currentSha256: inspection.document.sha256,
+      referenceSha256: null,
+      diff: null,
+    });
+  }
+  const historical = await runGit({
+    arguments: ["show", "--no-ext-diff", "--no-textconv", "--format=", specifier],
+    cwd: repository,
+    timeoutMs: GIT_TIMEOUT_MS,
+    maxOutputBytes: MAX_GIT_DOCUMENT_BYTES,
+  });
+  if (historical.status !== "ok") {
+    throw gitMessage(historical, "Could not read capture at the requested Git ref");
+  }
+  const referenceBytes = utf8(historical.stdout);
+  const referenceSha256 = sha256(referenceBytes);
+  if (referenceSha256 === inspection.document.sha256) {
+    await assertCaptureBundleStable(options, readBundle, inspection);
+    return Object.freeze({
+      status: "unchanged",
+      ref,
+      repositoryPath: path,
+      currentSha256: inspection.document.sha256,
+      referenceSha256,
+      diff: "",
+    });
+  }
+  const result = await runGit({
+    arguments: ["diff", "--no-ext-diff", "--no-textconv", "--unified=3", objectId, "--", literalPathspec],
+    cwd: repository,
+    timeoutMs: GIT_TIMEOUT_MS,
+    maxOutputBytes: MAX_DIFF_BYTES,
+  });
+  if (result.status !== "ok") throw gitMessage(result, "Could not diff capture bundle");
+  await assertCaptureBundleStable(options, readBundle, inspection);
+  return Object.freeze({
+    status: "changed",
+    ref,
+    repositoryPath: path,
+    currentSha256: inspection.document.sha256,
+    referenceSha256,
+    diff: utf8(result.stdout).toString("utf8"),
+  });
+}

package/src/clip/structured.ts

@@ -0,0 +1,432 @@
+import { captureUrl, type CaptureArguments, type CaptureScope } from "./args.js";
+import type { AcquisitionMethod, AcquiredPage } from "./acquire.js";
+import { countWords, type CaptureStatus, type ExtractedPage } from "./extract.js";
+import type { Article } from "./lib.js";
+import { decodeBytes, safeFetch } from "./network.js";
+import {
+  classifyPlatformUrl,
+  parseBlueskyCapture,
+  parseHackerNewsCapture,
+  parseRedditCapture,
+  renderCapturedDocument,
+  type CapturedContentEntry,
+  type CapturedDocument,
+  type CapturedEntry,
+  type PlatformUrl,
+} from "./platforms.js";
+
+export type PublicStructuredCapture = {
+  readonly extraction: ExtractedPage;
+  readonly evidence: string;
+};
+
+export type JsonFetcher = (url: URL, maxBytes: number, timeoutMs?: number) => Promise<unknown>;
+
+type AdapterDependencies = {
+  readonly fetchJson?: JsonFetcher;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const itemId = (value: unknown): string | null => {
+  if (typeof value === "string" && /^\d+$/.test(value)) return value;
+  if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) return String(value);
+  return null;
+};
+
+type HackerNewsPendingItem = { readonly id: string; readonly depth: number };
+
+const enqueueHackerNewsChildren = (
+  value: unknown,
+  depth: number,
+  maximumQueueSize: number,
+  queue: HackerNewsPendingItem[],
+  scheduled: Set<string>,
+): { readonly duplicate: boolean; readonly truncated: boolean } => {
+  if (!isRecord(value) || !Array.isArray(value.kids)) return { duplicate: false, truncated: false };
+  let duplicate = false;
+  for (const child of value.kids) {
+    const id = itemId(child);
+    if (id === null) continue;
+    if (scheduled.has(id)) {
+      duplicate = true;
+      continue;
+    }
+    if (queue.length >= maximumQueueSize) return { duplicate, truncated: true };
+    scheduled.add(id);
+    queue.push({ id, depth });
+  }
+  return { duplicate, truncated: false };
+};
+
+async function defaultJsonFetcher(
+  options: CaptureArguments,
+  url: URL,
+  maxBytes: number,
+  timeoutMs = options.timeoutMs,
+): Promise<unknown> {
+  const response = await safeFetch(url, {
+    timeoutMs,
+    maxBytes,
+    allowPrivateNetwork: options.allowPrivateNetwork,
+    userAgent: options.userAgent,
+    accept: "application/json",
+    retries: 2,
+  });
+  const text = decodeBytes(response.bytes, response.contentType);
+  try {
+    return JSON.parse(text) as unknown;
+  } catch (error) {
+    throw new Error(`invalid JSON from ${url.origin}`, { cause: error });
+  }
+}
+
+function serializedBytes(value: unknown): number {
+  try {
+    return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+  } catch {
+    return Number.POSITIVE_INFINITY;
+  }
+}
+
+function walkDocument(document: CapturedDocument): {
+  readonly pageItems: number;
+  readonly scopedItems: number;
+  readonly incomplete: boolean;
+  readonly rootIncomplete: boolean;
+  readonly blockedRoot: boolean;
+} {
+  let pageItems = 0;
+  let scopedItems = 0;
+  let incomplete = false;
+  let rootIncomplete = false;
+  let blockedRoot = false;
+  const active = new WeakSet<object>();
+  const visit = (entry: CapturedEntry, location: "ancestor" | "root" | "quote" | "reply"): void => {
+    if (active.has(entry)) {
+      incomplete = true;
+      return;
+    }
+    active.add(entry);
+    if (entry.kind === "boundary" || entry.kind === "more") {
+      incomplete = true;
+      if (location === "root") rootIncomplete = true;
+      active.delete(entry);
+      return;
+    }
+    const unavailable = entry.kind === "unavailable";
+    const unavailableButRepresented = unavailable && (entry.reason === "deleted" || entry.reason === "dead" || entry.reason === "removed");
+    const captured = entry.kind === "content" || unavailableButRepresented;
+    if (location === "root" && captured) pageItems += 1;
+    if (location === "reply" && captured) scopedItems += 1;
+    if (unavailable && (entry.reason === "not-found" || entry.reason === "blocked")) incomplete = true;
+    if (location === "root" && unavailable && (entry.reason === "not-found" || entry.reason === "blocked")) {
+      rootIncomplete = true;
+    }
+    if (location === "root" && unavailable && entry.reason === "blocked") blockedRoot = true;
+    if (entry.kind === "content") {
+      for (const quote of entry.quotes) visit(quote, "quote");
+      for (const reply of entry.replies) visit(reply, "reply");
+    } else if (entry.kind === "unavailable") {
+      for (const reply of entry.replies) visit(reply, "reply");
+    }
+    active.delete(entry);
+  };
+  for (const entry of document.ancestors) visit(entry, "ancestor");
+  for (const entry of document.roots) visit(entry, "root");
+  return { pageItems, scopedItems, incomplete, rootIncomplete, blockedRoot };
+}
+
+const rootContent = (document: CapturedDocument): CapturedContentEntry | null => {
+  const root = document.roots[0];
+  return root?.kind === "content" ? root : null;
+};
+
+function structuredStatus(
+  document: CapturedDocument,
+  scope: CaptureScope,
+  adapterWarnings: readonly string[],
+): {
+  readonly status: CaptureStatus;
+  readonly capturedItems: number;
+  readonly expectedItems: number | null;
+  readonly declaredItems: number | null;
+} {
+  const walked = walkDocument(document);
+  const root = rootContent(document);
+  if (scope === "page") {
+    return {
+      status: walked.blockedRoot
+        ? "blocked"
+        : walked.rootIncomplete || walked.pageItems === 0 || adapterWarnings.length > 0 ? "partial" : "complete",
+      capturedItems: walked.pageItems,
+      expectedItems: null,
+      declaredItems: null,
+    };
+  }
+  const declaredItems = root?.metrics.replies ?? null;
+  const expectedItems = declaredItems === null ? null : Math.max(declaredItems, walked.scopedItems);
+  if (walked.blockedRoot) {
+    return { status: "blocked", capturedItems: walked.scopedItems, expectedItems, declaredItems };
+  }
+  const shortOfDeclared = declaredItems !== null && walked.scopedItems < declaredItems;
+  return {
+    status: walked.incomplete || shortOfDeclared || adapterWarnings.length > 0 ? "partial" : "complete",
+    capturedItems: walked.scopedItems,
+    expectedItems,
+    declaredItems,
+  };
+}
+
+export function structuredCaptureFromDocument(
+  options: CaptureArguments,
+  document: CapturedDocument,
+  evidence: unknown,
+  method: AcquisitionMethod,
+  adapterWarnings: readonly string[],
+  extractor = `${document.platform}-public-api`,
+): PublicStructuredCapture {
+  const rendered = renderCapturedDocument(document);
+  const content = rendered.replace(/^# [^\n]+\n\n/, "").trim();
+  const root = rootContent(document);
+  const article: Article = {
+    content,
+    title: document.title,
+    author: root?.author?.name ?? null,
+    published: root?.createdAt ?? null,
+    description: null,
+  };
+  const completeness = structuredStatus(document, options.scope, [...adapterWarnings, ...document.warnings]);
+  const warnings = [...adapterWarnings, ...document.warnings];
+  if (completeness.declaredItems !== null && completeness.capturedItems > completeness.declaredItems) {
+    warnings.push(
+      `The source declared ${completeness.declaredItems} scoped items, but ${completeness.capturedItems} distinct items were captured; the expected count was normalized to the observed count.`,
+    );
+  }
+  if (completeness.status !== "complete") {
+    warnings.push(`Structured ${document.platform} capture is ${completeness.status}; limits or unavailable branches remain.`);
+  }
+  const acquisition: AcquiredPage = {
+    body: JSON.stringify(evidence),
+    contentType: "application/json",
+    finalUrl: captureUrl(options),
+    method,
+    warnings,
+  };
+  const wordCount = countWords(content);
+  const statusWeight: Readonly<Record<CaptureStatus, number>> = {
+    complete: 100_000,
+    partial: 60_000,
+    "auth-required": 0,
+    blocked: -10_000,
+    unsupported: -20_000,
+  };
+  return {
+    extraction: {
+      article,
+      canonicalUrl: new URL(document.sourceUrl),
+      platform: document.platform,
+      status: completeness.status,
+      score: statusWeight[completeness.status] + Math.min(content.length, 50_000) + completeness.capturedItems * 50,
+      wordCount,
+      expectedItems: completeness.expectedItems,
+      capturedItems: completeness.capturedItems,
+      extractor,
+      warnings,
+      acquisition,
+    },
+    evidence: `${JSON.stringify(evidence, null, 2)}\n`,
+  };
+}
+
+async function captureHackerNews(
+  options: CaptureArguments,
+  classified: Extract<PlatformUrl, { readonly platform: "hacker-news" }>,
+  fetchJson: JsonFetcher,
+): Promise<PublicStructuredCapture> {
+  const endpoint = (id: string): URL => new URL(`https://hacker-news.firebaseio.com/v0/item/${encodeURIComponent(id)}.json`);
+  const deadline = Date.now() + options.timeoutMs;
+  let remainingBytes = options.maxHtmlBytes;
+  const remainingTime = (): number => {
+    const value = deadline - Date.now();
+    if (value <= 0) throw new Error(`Hacker News capture exceeded the ${options.timeoutMs}ms total deadline`);
+    return value;
+  };
+  const rootAllocation = Math.min(remainingBytes, 1024 * 1024);
+  if (rootAllocation < 1) throw new Error("Hacker News capture has no remaining response-byte budget");
+  remainingBytes -= rootAllocation;
+  const root = await fetchJson(endpoint(classified.itemId), rootAllocation, remainingTime());
+  const rootBytes = serializedBytes(root);
+  if (!Number.isFinite(rootBytes) || rootBytes > rootAllocation) {
+    throw new Error("Hacker News root item exceeded its bounded JSON allocation");
+  }
+  remainingBytes += rootAllocation - rootBytes;
+  if (!isRecord(root) || itemId(root.id) === null) throw new Error("Hacker News API returned no root item");
+
+  if (options.scope === "page") {
+    const evidence = { root, descendants: [] };
+    const parsed = parseHackerNewsCapture(evidence, classified.href, {
+      limits: { maxItems: options.maxItems, maxDepth: options.maxDepth },
+    });
+    if (!parsed.ok) throw new Error(parsed.error.message);
+    return structuredCaptureFromDocument(options, parsed.document, evidence, "hacker-news-api", []);
+  }
+
+  const descendants: unknown[] = [];
+  const warnings: string[] = [];
+  const scheduled = new Set<string>([classified.itemId]);
+  const queue: HackerNewsPendingItem[] = [];
+  const initialChildren = enqueueHackerNewsChildren(
+    root,
+    1,
+    Math.max(0, options.maxItems - 1),
+    queue,
+    scheduled,
+  );
+  let duplicateChildren = initialChildren.duplicate;
+  let limited = initialChildren.truncated;
+  while (queue.length > 0 && descendants.length + 1 < options.maxItems) {
+    const remaining = options.maxItems - descendants.length - 1;
+    const batchSize = Math.min(8, remaining, queue.length, remainingBytes);
+    if (batchSize < 1) {
+      limited = true;
+      break;
+    }
+    const batch = queue.splice(0, batchSize);
+    const allocation = Math.min(64 * 1024, Math.floor(remainingBytes / batch.length));
+    remainingBytes -= allocation * batch.length;
+    const fetched = await Promise.all(batch.map(async ({ id, depth }) => {
+      try {
+        const value = await fetchJson(endpoint(id), allocation, remainingTime());
+        const bytes = serializedBytes(value);
+        if (!Number.isFinite(bytes) || bytes > allocation) {
+          return { id, depth, value: null, warning: `Hacker News item ${id} exceeded its bounded JSON allocation.` };
+        }
+        remainingBytes += allocation - bytes;
+        return { id, depth, value, warning: null };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { id, depth, value: null, warning: `Could not fetch Hacker News item ${id}: ${message}` };
+      }
+    }));
+    const childrenToSchedule: { readonly value: unknown; readonly depth: number }[] = [];
+    for (const result of fetched) {
+      if (result.warning !== null) warnings.push(result.warning);
+      if (result.value === null) continue;
+      descendants.push(result.value);
+      childrenToSchedule.push({ value: result.value, depth: result.depth });
+    }
+    const maximumQueueSize = Math.max(0, options.maxItems - descendants.length - 1);
+    for (const result of childrenToSchedule) {
+      const atDepthLimit = result.depth >= options.maxDepth - 1;
+      const enqueued = enqueueHackerNewsChildren(
+        result.value,
+        result.depth + 1,
+        atDepthLimit ? queue.length : maximumQueueSize,
+        queue,
+        scheduled,
+      );
+      duplicateChildren = duplicateChildren || enqueued.duplicate;
+      limited = limited || enqueued.truncated;
+    }
+  }
+  if (duplicateChildren) warnings.push("Hacker News duplicate or cyclic child IDs were skipped.");
+  if (queue.length > 0 || limited) {
+    warnings.push("Hacker News descendants exceeded the configured item, depth, byte, or total-deadline limit.");
+  }
+  const evidence = { root, descendants };
+  const parsed = parseHackerNewsCapture(evidence, classified.href, {
+    limits: { maxItems: options.maxItems, maxDepth: options.maxDepth },
+  });
+  if (!parsed.ok) throw new Error(parsed.error.message);
+  const document: CapturedDocument = {
+    ...parsed.document,
+    warnings: [...parsed.document.warnings, ...warnings],
+  };
+  return structuredCaptureFromDocument(options, document, evidence, "hacker-news-api", warnings);
+}
+
+async function captureBluesky(
+  options: CaptureArguments,
+  classified: Extract<PlatformUrl, { readonly platform: "bluesky" }>,
+  fetchJson: JsonFetcher,
+): Promise<PublicStructuredCapture> {
+  let did = classified.actor;
+  const evidence: Record<string, unknown> = {};
+  if (!did.startsWith("did:")) {
+    const resolveUrl = new URL("https://public.api.bsky.app/xrpc/com.atproto.identity.resolveHandle");
+    resolveUrl.searchParams.set("handle", did);
+    const resolution = await fetchJson(resolveUrl, Math.min(options.maxHtmlBytes, 1024 * 1024));
+    evidence.resolution = resolution;
+    if (!isRecord(resolution) || typeof resolution.did !== "string" || !resolution.did.startsWith("did:")) {
+      throw new Error(`Bluesky could not resolve ${classified.actor}`);
+    }
+    did = resolution.did;
+  }
+  const threadUrl = new URL("https://public.api.bsky.app/xrpc/app.bsky.feed.getPostThread");
+  threadUrl.searchParams.set("uri", `at://${did}/app.bsky.feed.post/${classified.postId}`);
+  threadUrl.searchParams.set("depth", options.scope === "page" ? "0" : String(Math.min(options.maxDepth, 1000)));
+  threadUrl.searchParams.set("parentHeight", String(Math.min(options.maxDepth, 1000)));
+  const thread = await fetchJson(threadUrl, options.maxHtmlBytes);
+  evidence.thread = thread;
+  const parsed = parseBlueskyCapture(thread, classified.href, {
+    limits: { maxItems: options.maxItems, maxDepth: options.maxDepth },
+  });
+  if (!parsed.ok) throw new Error(parsed.error.message);
+  return structuredCaptureFromDocument(options, parsed.document, evidence, "bluesky-api", []);
+}
+
+function rootOnlyRedditInput(input: unknown): unknown {
+  if (!Array.isArray(input)) return input;
+  const values: readonly unknown[] = input;
+  const post: unknown = values[0];
+  return post === undefined ? values : [post];
+}
+
+function redditHasPagination(input: unknown): boolean {
+  if (!Array.isArray(input)) return false;
+  const comments: unknown = input[1];
+  if (!isRecord(comments)) return false;
+  const data = isRecord(comments.data) ? comments.data : null;
+  return data !== null && data.after !== undefined && data.after !== null;
+}
+
+/** Best-effort Reddit listing JSON. This endpoint is public but unofficial and may be denied by Reddit. */
+async function captureReddit(
+  options: CaptureArguments,
+  classified: Extract<PlatformUrl, { readonly platform: "reddit" }>,
+  fetchJson: JsonFetcher,
+): Promise<PublicStructuredCapture> {
+  const endpoint = new URL(`https://www.reddit.com/comments/${encodeURIComponent(classified.postId)}.json`);
+  endpoint.searchParams.set("raw_json", "1");
+  endpoint.searchParams.set("limit", String(Math.max(1, options.maxItems - 1)));
+  endpoint.searchParams.set("depth", String(options.scope === "page" ? 0 : options.maxDepth));
+  if (classified.commentId !== null) endpoint.searchParams.set("comment", classified.commentId);
+  const evidence = await fetchJson(endpoint, options.maxHtmlBytes, options.timeoutMs);
+  const parserInput = options.scope === "page" ? rootOnlyRedditInput(evidence) : evidence;
+  const parsed = parseRedditCapture(parserInput, classified.href, {
+    limits: { maxItems: options.maxItems, maxDepth: options.maxDepth },
+  });
+  if (!parsed.ok) throw new Error(parsed.error.message);
+  const warnings = options.scope !== "page" && redditHasPagination(evidence)
+    ? ["Reddit JSON returned a pagination cursor; additional comments remain uncaptured."]
+    : [];
+  const storedEvidence = options.scope === "page" ? parserInput : evidence;
+  return structuredCaptureFromDocument(options, parsed.document, storedEvidence, "reddit-json", warnings, "reddit-json");
+}
+
+/** Use stable public APIs where they preserve more structure than page scraping. */
+export async function acquirePublicStructured(
+  options: CaptureArguments,
+  dependencies: AdapterDependencies = {},
+): Promise<PublicStructuredCapture | null> {
+  const classified = classifyPlatformUrl(captureUrl(options).href);
+  if (classified === null) return null;
+  const fetchJson = dependencies.fetchJson
+    ?? ((url, maxBytes, timeoutMs) => defaultJsonFetcher(options, url, maxBytes, timeoutMs));
+  if (classified.platform === "hacker-news") return captureHackerNews(options, classified, fetchJson);
+  if (classified.platform === "bluesky") return captureBluesky(options, classified, fetchJson);
+  if (classified.platform === "reddit") return captureReddit(options, classified, fetchJson);
+  return null;
+}