Improve lookup hints for private-address validation failures

Detect private/localhost URL validation failures and show actionable
hints instead of always suggesting authorized fetch.

- In lookup/traverse fetch failures, suggest -p/--allow-private-address
  when the failure is a private-address UrlError.
- In recurse step failures, explain that recursive fetches always block
  private/localhost targets and suggest best-effort suppression or
  explicit non-recursive fetches.
- Keep existing -a/--authorized-fetch guidance for non-UrlError cases.

Also adds unit tests for the hint classification helper.

#608 (comment)
#608 (comment)
#608 (comment)

Author: dahlia

packages/cli/src/lookup.test.ts

@@ -2,6 +2,7 @@ import { Activity, Note } from "@fedify/vocab";
 import { clearActiveConfig, setActiveConfig } from "@optique/config";
 import { runWithConfig } from "@optique/config/run";
 import { parse } from "@optique/core/parser";
+import { UrlError } from "@fedify/vocab-runtime";
 import assert from "node:assert/strict";
 import { Buffer } from "node:buffer";
 import { createWriteStream } from "node:fs";
@@ -16,6 +17,7 @@ import {
   clearTimeoutSignal,
   collectRecursiveObjects,
   createTimeoutSignal,
+  getLookupFailureHint,
   getRecursiveTargetId,
   lookupCommand,
   RecursiveLookupError,
@@ -618,6 +620,29 @@ test("getRecursiveTargetId - returns null for unknown recurse property", () => {
   );
 });
 
+test("getLookupFailureHint - suggests private-address for UrlError", () => {
+  assert.equal(
+    getLookupFailureHint(new UrlError("Localhost is not allowed")),
+    "private-address",
+  );
+});
+
+test("getLookupFailureHint - suggests recursive-private-address in recurse mode", () => {
+  assert.equal(
+    getLookupFailureHint(new UrlError("Invalid or private address"), {
+      recursive: true,
+    }),
+    "recursive-private-address",
+  );
+});
+
+test("getLookupFailureHint - suggests authorized-fetch for non-URL errors", () => {
+  assert.equal(
+    getLookupFailureHint(new Error("401 Unauthorized")),
+    "authorized-fetch",
+  );
+});
+
 test("collectRecursiveObjects - follows chain up to depth limit", async () => {
   const note1 = new Note({
     id: new URL("https://example.com/notes/1"),

packages/cli/src/lookup.ts

@@ -12,7 +12,7 @@ import {
   Object as APObject,
   traverseCollection,
 } from "@fedify/vocab";
-import type { DocumentLoader } from "@fedify/vocab-runtime";
+import { type DocumentLoader, UrlError } from "@fedify/vocab-runtime";
 import type { ResourceDescriptor } from "@fedify/webfinger";
 import { getLogger } from "@logtape/logtape";
 import { bindConfig } from "@optique/config";
@@ -491,6 +491,53 @@ function handleTimeoutError(
   );
 }
 
+function isPrivateAddressError(error: unknown): boolean {
+  if (error instanceof UrlError) return true;
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  const lowerMessage = errorMessage.toLowerCase();
+  return (
+    lowerMessage.includes("private address") ||
+    lowerMessage.includes("private ip") ||
+    lowerMessage.includes("localhost") ||
+    lowerMessage.includes("loopback")
+  );
+}
+
+export function getLookupFailureHint(
+  error: unknown,
+  options: { recursive?: boolean } = {},
+): "private-address" | "recursive-private-address" | "authorized-fetch" {
+  if (isPrivateAddressError(error)) {
+    return options.recursive ? "recursive-private-address" : "private-address";
+  }
+  return "authorized-fetch";
+}
+
+function printLookupFailureHint(
+  authLoader: DocumentLoader | undefined,
+  error: unknown,
+  options: { recursive?: boolean } = {},
+): void {
+  if (authLoader != null) return;
+  switch (getLookupFailureHint(error, options)) {
+    case "private-address":
+      printError(
+        message`The URL appears to be private or localhost.  Try with -p/--allow-private-address.`,
+      );
+      return;
+    case "recursive-private-address":
+      printError(
+        message`Recursive fetches do not allow private/localhost URLs.  Use -S/--suppress-errors to skip blocked steps, or fetch those targets explicitly without --recurse.`,
+      );
+      return;
+    case "authorized-fetch":
+      printError(
+        message`It may be a private object.  Try with -a/--authorized-fetch.`,
+      );
+      return;
+  }
+}
+
 /**
  * Gets the next recursion target URL from an ActivityPub object.
  */
@@ -796,11 +843,7 @@ export async function runLookup(
           handleTimeoutError(spinner, command.timeout, url);
         } else {
           spinner.fail(`Failed to fetch object: ${colors.red(url)}.`);
-          if (authLoader == null) {
-            printError(
-              message`It may be a private object.  Try with -a/--authorized-fetch.`,
-            );
-          }
+          printLookupFailureHint(authLoader, error);
         }
         await finalizeAndExit(1);
         return;
@@ -874,9 +917,7 @@ export async function runLookup(
         } else {
           spinner.fail("Failed to recursively fetch object.");
           if (authLoader == null) {
-            printError(
-              message`It may be a private object.  Try with -a/--authorized-fetch.`,
-            );
+            printLookupFailureHint(authLoader, error, { recursive: true });
           } else {
             printError(
               message`Use the -S/--suppress-errors option to suppress partial errors.`,
@@ -936,11 +977,7 @@ export async function runLookup(
           handleTimeoutError(spinner, command.timeout, url);
         } else {
           spinner.fail(`Failed to fetch object: ${colors.red(url)}.`);
-          if (authLoader == null) {
-            printError(
-              message`It may be a private object.  Try with -a/--authorized-fetch.`,
-            );
-          }
+          printLookupFailureHint(authLoader, error);
         }
         await finalizeAndExit(1);
         return;
@@ -1009,9 +1046,7 @@ export async function runLookup(
             `Failed to complete the traversal for: ${colors.red(url)}.`,
           );
           if (authLoader == null) {
-            printError(
-              message`It may be a private object.  Try with -a/--authorized-fetch.`,
-            );
+            printLookupFailureHint(authLoader, error);
           } else {
             printError(
               message`Use the -S/--suppress-errors option to suppress partial errors.`,