Tighten lookup loader safety and document public helpers

Apply follow-up fixes from review for config validation, stream output\nbehavior, and API documentation.\n\nThe document loader now defaults to deny private addresses, lookup\nconfig schema now enforces traverse/recurse mutual exclusion and\nrecurseDepth dependency, and recursive helper exports now include\nJSDoc. Image rendering now only runs when writing to stdout.\n\nhttps://github.com//pull/608#discussion_r2901510813\nhttps://github.com//pull/608#discussion_r2901510814\nhttps://github.com//pull/608#discussion_r2901510815\nhttps://github.com//pull/608#discussion_r2901510816\nhttps://github.com//pull/608#discussion_r2901510817\nhttps://github.com//pull/608#discussion_r2901515752\nhttps://github.com//pull/608#discussion_r2901515762\n\nCo-Authored-By: Codex <codex@openai.com>

Author: dahlia

packages/cli/src/config.ts

@@ -6,6 +6,8 @@ import { parse as parseToml } from "smol-toml";
 import {
   array,
   boolean,
+  check,
+  forward,
   type InferOutput,
   integer,
   minValue,
@@ -28,28 +30,44 @@ const webfingerSchema = object({
 /**
  * Schema for the lookup command configuration.
  */
-const lookupSchema = object({
-  authorizedFetch: optional(boolean()),
-  firstKnock: optional(
-    picklist(["draft-cavage-http-signatures-12", "rfc9421"]),
+const lookupSchema = pipe(
+  object({
+    authorizedFetch: optional(boolean()),
+    firstKnock: optional(
+      picklist(["draft-cavage-http-signatures-12", "rfc9421"]),
+    ),
+    traverse: optional(boolean()),
+    recurse: optional(
+      picklist([
+        "replyTarget",
+        "quoteUrl",
+        "https://www.w3.org/ns/activitystreams#inReplyTo",
+        "https://www.w3.org/ns/activitystreams#quoteUrl",
+        "https://misskey-hub.net/ns#_misskey_quote",
+        "http://fedibird.com/ns#quoteUri",
+      ]),
+    ),
+    recurseDepth: optional(pipe(number(), integer(), minValue(1))),
+    suppressErrors: optional(boolean()),
+    defaultFormat: optional(picklist(["default", "raw", "compact", "expand"])),
+    separator: optional(string()),
+    timeout: optional(number()),
+  }),
+  forward(
+    check(
+      (input) => !(input.traverse === true && input.recurse != null),
+      "lookup.traverse and lookup.recurse cannot be used together.",
+    ),
+    ["recurse"],
   ),
-  traverse: optional(boolean()),
-  recurse: optional(
-    picklist([
-      "replyTarget",
-      "quoteUrl",
-      "https://www.w3.org/ns/activitystreams#inReplyTo",
-      "https://www.w3.org/ns/activitystreams#quoteUrl",
-      "https://misskey-hub.net/ns#_misskey_quote",
-      "http://fedibird.com/ns#quoteUri",
-    ]),
+  forward(
+    check(
+      (input) => input.recurse != null || input.recurseDepth == null,
+      "lookup.recurseDepth requires lookup.recurse.",
+    ),
+    ["recurseDepth"],
   ),
-  recurseDepth: optional(pipe(number(), integer(), minValue(1))),
-  suppressErrors: optional(boolean()),
-  defaultFormat: optional(picklist(["default", "raw", "compact", "expand"])),
-  separator: optional(string()),
-  timeout: optional(number()),
-});
+);
 
 /**
  * Schema for the inbox command configuration.

packages/cli/src/docloader.ts

@@ -12,6 +12,10 @@ export interface DocumentLoaderOptions {
   allowPrivateAddress?: boolean;
 }
 
+/**
+ * Returns a cache prefix that separates document-loader entries by user agent
+ * and private-address policy.
+ */
 export function getDocumentLoaderCachePrefix(
   userAgent: string | undefined,
   allowPrivateAddress: boolean,
@@ -26,7 +30,7 @@ export function getDocumentLoaderCachePrefix(
 }
 
 export async function getDocumentLoader(
-  { userAgent, allowPrivateAddress = true }: DocumentLoaderOptions = {},
+  { userAgent, allowPrivateAddress = false }: DocumentLoaderOptions = {},
 ): Promise<DocumentLoader> {
   const cacheKey = `${userAgent ?? ""}:${allowPrivateAddress}`;
   if (documentLoaders[cacheKey]) return documentLoaders[cacheKey];

packages/cli/src/lookup.ts

@@ -290,6 +290,9 @@ export class TimeoutError extends Error {
   }
 }
 
+/**
+ * Error thrown when a recursive lookup target cannot be fetched.
+ */
 export class RecursiveLookupError extends Error {
   target: string;
   constructor(target: string) {
@@ -405,7 +408,7 @@ export async function writeObjectToStream(
   if (object instanceof APObject) {
     imageUrls = await findAllImages(object);
   }
-  if (!outputPath && imageUrls.length > 0) {
+  if (localStream === process.stdout && imageUrls.length > 0) {
     await renderImages(imageUrls);
   }
 }
@@ -475,6 +478,9 @@ function handleTimeoutError(
   );
 }
 
+/**
+ * Gets the next recursion target URL from an ActivityPub object.
+ */
 export function getRecursiveTargetId(
   object: APObject,
   recurseProperty: RecurseProperty,
@@ -488,6 +494,9 @@ export function getRecursiveTargetId(
   return quoteUrl instanceof URL ? quoteUrl : null;
 }
 
+/**
+ * Collects recursively linked objects up to a depth limit.
+ */
 export async function collectRecursiveObjects(
   initialObject: APObject,
   recurseProperty: RecurseProperty,