@fedify/cli 2.4.0-dev.2155 → 2.4.0-dev.2157

package/dist/deno.js

@@ -1,5 +1,5 @@
 import "temporal-polyfill";
 //#region deno.json
-var version = "2.4.0-dev.2155+2ccc5085";
+var version = "2.4.0-dev.2157+b76e5888";
 //#endregion
 export { version };

package/dist/diagnostics.js

@@ -0,0 +1,70 @@
+import "temporal-polyfill";
+import { FetchError, UrlError } from "@fedify/vocab-runtime";
+import "@fedify/vocab";
+//#region src/diagnostics.ts
+/** Records loader failures that lookupObject would otherwise swallow or wrap. */
+function createLookupDiagnostics(documentLoader, contextLoader) {
+	let objectFailure;
+	let contextFailure;
+	const wrap = (loader, source, record) => async (url, options) => {
+		try {
+			const document = await loader(url, options);
+			record(void 0);
+			return document;
+		} catch (error) {
+			record({
+				error,
+				source
+			});
+			throw error;
+		}
+	};
+	return {
+		documentLoader: wrap(documentLoader, "object", (e) => objectFailure = e),
+		contextLoader: wrap(contextLoader, "context", (e) => contextFailure = e),
+		clearFailures() {
+			objectFailure = void 0;
+			contextFailure = void 0;
+		},
+		getObjectFailure: () => objectFailure,
+		getContextFailure: () => contextFailure
+	};
+}
+function escapeControlCharacters(message) {
+	return message.replace(/[\x00-\x1f\x7f-\x9f]/g, (character) => `\\x${character.charCodeAt(0).toString(16).padStart(2, "0")}`);
+}
+/** Describes a failure without recommending signing unless HTTP supports it. */
+function describeLookupFailure(failure, authorizedFetch) {
+	const error = failure?.error;
+	const http = error instanceof FetchError ? /^(.+): HTTP (\d{3}): \1$/s.exec(error.message) : null;
+	if (http != null) {
+		const status = Number(http[2]);
+		const suggestsAuthorizedFetch = failure?.source === "object" && !authorizedFetch && [
+			401,
+			403,
+			404
+		].includes(status);
+		return {
+			message: escapeControlCharacters(`HTTP ${status} from ${http[1]}.`) + (suggestsAuthorizedFetch ? "  It may be a private object.  Try with -a/--authorized-fetch." : ""),
+			suggestsAuthorizedFetch
+		};
+	}
+	const causes = [];
+	const seen = /* @__PURE__ */ new Set();
+	let cause = error;
+	while (cause instanceof Error && !seen.has(cause) && causes.length < 8) {
+		seen.add(cause);
+		causes.push(cause);
+		if (cause instanceof UrlError && cause.reason === "dns" || cause instanceof TypeError && /dns error|failed to lookup address information/i.test(cause.message) || "code" in cause && (cause.code === "ENOTFOUND" || cause.code === "EAI_AGAIN")) return {
+			message: "Could not resolve the host in the URL.  Check the URL and your network connection.",
+			suggestsAuthorizedFetch: false
+		};
+		cause = cause.cause;
+	}
+	return {
+		message: escapeControlCharacters(causes.length > 0 ? causes.map((e) => e.message).join(": ") : error == null ? "Could not fetch or parse the object.  Check the URL or actor handle." : String(error)),
+		suggestsAuthorizedFetch: false
+	};
+}
+//#endregion
+export { createLookupDiagnostics, describeLookupFailure };

package/dist/lookup.js

@@ -4,9 +4,10 @@ import { colorEnabled, colors, describeError, formatObject } from "./utils.js";
 import { configureLogging } from "./log.js";
 import { getContextLoader, getDocumentLoader as getDocumentLoader$1 } from "./docloader.js";
 import { spawnTemporaryServer } from "./tempserver.js";
+import { createLookupDiagnostics, describeLookupFailure } from "./diagnostics.js";
 import { renderImages } from "./imagerenderer.js";
 import process from "node:process";
-import { message, optionNames } from "@optique/core";
+import { message, optionNames, text } from "@optique/core";
 import { printError } from "@optique/run";
 import { createWriteStream } from "node:fs";
 import { UrlError, expandIPv6Address, isValidPublicIPv4Address, isValidPublicIPv6Address } from "@fedify/vocab-runtime";
@@ -164,6 +165,9 @@ function wrapDocumentLoaderWithTimeout(loader, timeoutSeconds) {
 		return loader(url, {
 			...options,
 			signal
+		}).catch((error) => {
+			if (signal?.aborted) throw signal.reason;
+			throw error;
 		}).finally(() => clearTimeoutSignal(signal));
 	};
 }
@@ -174,7 +178,7 @@ function handleTimeoutError(spinner, timeoutSeconds, url) {
 }
 function isPrivateAddressError(error) {
 	const lowerMessage = describeError(error).toLowerCase();
-	if (error instanceof UrlError) return lowerMessage.includes("invalid or private address") || lowerMessage.includes("localhost is not allowed");
+	if (error instanceof UrlError) return error.reason === "disallowed" && (lowerMessage.includes("invalid or private address") || lowerMessage.includes("localhost is not allowed"));
 	return lowerMessage.includes("private address") || lowerMessage.includes("private ip") || lowerMessage.includes("localhost") || lowerMessage.includes("loopback");
 }
 function getPrivateUrlCandidate(candidate) {
@@ -212,6 +216,7 @@ function printRecursivePrivateContextHint(privateContextUrl) {
 	printError(message`Recursive JSON-LD context URL ${url(privateContextUrl)} is always blocked, even with ${optionNames(["-p", "--allow-private-address"])}.  Use ${optionNames(["-S", "--suppress-errors"])} to skip blocked steps.`);
 }
 function getLookupFailureHint(error, options = {}) {
+	if (error instanceof UrlError && error.reason === "dns") return "dns";
 	if (isPrivateAddressError(error)) return options.recursive ? "recursive-private-address" : "private-address";
 	return "authorized-fetch";
 }
@@ -225,6 +230,9 @@ function printLookupFailureHint(authLoader, error, options = {}) {
 	const hint = getLookupFailureHint(error, options);
 	if (!shouldPrintLookupFailureHint(authLoader, hint)) return;
 	switch (hint) {
+		case "dns":
+			printError(message`DNS lookup failed.  Check the hostname and network connectivity.`);
+			return;
 		case "private-address":
 			printError(message`The URL appears to be private or localhost.  Try with ${optionNames(["-p", "--allow-private-address"])}.`);
 			return;
@@ -305,6 +313,29 @@ async function runLookup(command, deps = {}) {
 		exit: (code) => process.exit(code),
 		...deps
 	};
+	const lookupDiagnosed = async (identifier, options) => {
+		const diagnostics = createLookupDiagnostics(options.documentLoader, options.contextLoader);
+		try {
+			const object = await effectiveDeps.lookupObject(identifier, {
+				...options,
+				...diagnostics
+			});
+			return {
+				object,
+				failure: object == null ? diagnostics.getObjectFailure() ?? diagnostics.getContextFailure() : void 0,
+				thrownError: void 0
+			};
+		} catch (error) {
+			return {
+				object: null,
+				thrownError: error,
+				failure: diagnostics.getContextFailure() ?? diagnostics.getObjectFailure() ?? {
+					error,
+					source: "other"
+				}
+			};
+		}
+	};
 	if (command.urls.length < 1) {
 		printError(message`At least one URL or actor handle must be provided.`);
 		effectiveDeps.exit(1);
@@ -556,39 +587,33 @@ async function runLookup(command, deps = {}) {
 		for (let urlIndex = 0; urlIndex < command.urls.length; urlIndex++) {
 			const url = command.urls[urlIndex];
 			if (urlIndex > 0) spinner.text = `Looking up collection ${urlIndex + 1}/${command.urls.length}...`;
-			let collection = null;
-			try {
-				collection = await effectiveDeps.lookupObject(url, {
-					documentLoader: initialAuthLoader ?? initialDocumentLoader,
-					contextLoader,
-					userAgent: command.userAgent
-				});
-			} catch (error) {
-				if (error instanceof TimeoutError) handleTimeoutError(spinner, command.timeout, url);
+			const result = await lookupDiagnosed(url, {
+				documentLoader: initialAuthLoader ?? initialDocumentLoader,
+				contextLoader,
+				userAgent: command.userAgent
+			});
+			const collection = result.object;
+			if (collection == null) {
+				if (result.thrownError instanceof TimeoutError || result.failure?.error instanceof TimeoutError) handleTimeoutError(spinner, command.timeout, url);
 				else {
 					spinner.fail(`Failed to fetch object: ${colors.red(url)}.`);
-					printLookupFailureHint(authLoader, error);
+					printError(message`${text(describeLookupFailure(result.failure, authLoader != null).message)}`);
 				}
 				await finalizeAndExit(1);
 				return;
 			}
-			if (collection == null) {
-				spinner.fail(`Failed to fetch object: ${colors.red(url)}.`);
-				if (authLoader == null) printError(message`It may be a private object.  Try with ${optionNames(["-a", "--authorized-fetch"])}.`);
-				await finalizeAndExit(1);
-				return;
-			}
 			if (!(collection instanceof Collection)) {
 				spinner.fail(`Not a collection: ${colors.red(url)}.  The -t/--traverse option requires a collection.`);
 				await finalizeAndExit(1);
 				return;
 			}
 			spinner.succeed(`Fetched collection: ${colors.green(url)}.`);
+			const diagnostics = createLookupDiagnostics(authLoader ?? documentLoader, contextLoader);
 			try {
 				if (command.reverse) {
 					const { items: traversedItems, error: traversalError } = await collectAsyncItems(effectiveDeps.traverseCollection(collection, {
-						documentLoader: authLoader ?? documentLoader,
-						contextLoader,
+						documentLoader: diagnostics.documentLoader,
+						contextLoader: diagnostics.contextLoader,
 						suppressError: command.suppressErrors
 					}));
 					for (let index = traversedItems.length - 1; index >= 0; index--) {
@@ -601,7 +626,14 @@ async function runLookup(command, deps = {}) {
 								url,
 								error
 							});
-							spinner.fail(`Failed to write output for: ${colors.red(url)}.`);
+							if (error instanceof TimeoutError) handleTimeoutError(spinner, command.timeout, url);
+							else {
+								spinner.fail(`Failed to write output for: ${colors.red(url)}.`);
+								printError(message`${text(describeLookupFailure({
+									error,
+									source: "other"
+								}, authLoader != null).message)}`);
+							}
 							await finalizeAndExit(1);
 							return;
 						}
@@ -609,8 +641,8 @@ async function runLookup(command, deps = {}) {
 					}
 					if (traversalError != null) throw traversalError;
 				} else for await (const item of effectiveDeps.traverseCollection(collection, {
-					documentLoader: authLoader ?? documentLoader,
-					contextLoader,
+					documentLoader: diagnostics.documentLoader,
+					contextLoader: diagnostics.contextLoader,
 					suppressError: command.suppressErrors
 				})) {
 					try {
@@ -621,23 +653,38 @@ async function runLookup(command, deps = {}) {
 							url,
 							error
 						});
-						spinner.fail(`Failed to write output for: ${colors.red(url)}.`);
+						if (error instanceof TimeoutError) handleTimeoutError(spinner, command.timeout, url);
+						else {
+							spinner.fail(`Failed to write output for: ${colors.red(url)}.`);
+							printError(message`${text(describeLookupFailure({
+								error,
+								source: "other"
+							}, authLoader != null).message)}`);
+						}
 						await finalizeAndExit(1);
 						return;
 					}
 					totalItems++;
+					diagnostics.clearFailures();
 				}
 			} catch (error) {
 				logger.error("Failed to complete the traversal for {url}: {error}", {
 					url,
 					error
 				});
-				if (error instanceof TimeoutError) handleTimeoutError(spinner, command.timeout, url);
+				const failure = diagnostics.getContextFailure() ?? diagnostics.getObjectFailure() ?? {
+					error,
+					source: "other"
+				};
+				if (error instanceof TimeoutError || failure.error instanceof TimeoutError) handleTimeoutError(spinner, command.timeout, url);
 				else {
 					spinner.fail(`Failed to complete the traversal for: ${colors.red(url)}.`);
-					const hint = getLookupFailureHint(error);
-					if (shouldSuggestSuppressErrorsForLookupFailure(authLoader, hint)) printError(message`Use the ${optionNames(["-S", "--suppress-errors"])} option to suppress partial errors.`);
-					else printLookupFailureHint(authLoader, error);
+					if (isPrivateAddressError(failure.error)) printLookupFailureHint(authLoader, failure.error);
+					else {
+						const diagnostic = describeLookupFailure(failure, authLoader != null);
+						printError(message`${text(diagnostic.message)}`);
+						if (!diagnostic.suggestsAuthorizedFetch && !command.suppressErrors) printError(message`Use the -S/--suppress-errors option to suppress partial errors.`);
+					}
 				}
 				await finalizeAndExit(1);
 				return;
@@ -647,31 +694,24 @@ async function runLookup(command, deps = {}) {
 		await finalizeAndExit(0);
 		return;
 	}
-	const promises = [];
-	for (const url of command.urls) promises.push(effectiveDeps.lookupObject(url, {
+	const objects = await Promise.all(command.urls.map((url) => lookupDiagnosed(url, {
 		documentLoader: initialAuthLoader ?? initialDocumentLoader,
 		contextLoader,
 		userAgent: command.userAgent
-	}).catch((error) => {
-		if (error instanceof TimeoutError) handleTimeoutError(spinner, command.timeout, url);
-		throw error;
-	}));
-	let objects = [];
-	try {
-		objects = await Promise.all(promises);
-	} catch (_error) {
-		await finalizeAndExit(1);
-		return;
-	}
+	})));
 	spinner.stop();
 	let success = true;
 	let printedCount = 0;
 	const successfulObjects = [];
-	for (const [i, obj] of objects.entries()) {
+	for (const [i, result] of objects.entries()) {
+		const obj = result.object;
 		const url = command.urls[i];
 		if (obj == null) {
-			spinner.fail(`Failed to fetch ${colors.red(url)}`);
-			if (authLoader == null) printError(message`It may be a private object.  Try with ${optionNames(["-a", "--authorized-fetch"])}.`);
+			if (result.thrownError instanceof TimeoutError || result.failure?.error instanceof TimeoutError) handleTimeoutError(spinner, command.timeout, url);
+			else {
+				spinner.fail(`Failed to fetch ${colors.red(url)}`);
+				printError(message`${text(describeLookupFailure(result.failure, authLoader != null).message)}`);
+			}
 			success = false;
 		} else {
 			spinner.succeed(`Fetched object: ${colors.green(url)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/cli",
-  "version": "2.4.0-dev.2155+2ccc5085",
+  "version": "2.4.0-dev.2157+b76e5888",
   "type": "module",
   "files": [
     "README.md",
@@ -88,21 +88,22 @@
     "temporal-polyfill": "^1.0.1",
     "valibot": "^1.4.0",
     "yaml": "^2.9.0",
-    "@fedify/init": "2.4.0-dev.2155+2ccc5085",
-    "@fedify/fedify": "2.4.0-dev.2155+2ccc5085",
-    "@fedify/sqlite": "2.4.0-dev.2155+2ccc5085",
-    "@fedify/relay": "2.4.0-dev.2155+2ccc5085",
-    "@fedify/vocab": "2.4.0-dev.2155+2ccc5085",
-    "@fedify/vocab-runtime": "2.4.0-dev.2155+2ccc5085",
-    "@fedify/vocab-tools": "2.4.0-dev.2155+2ccc5085",
-    "@fedify/webfinger": "2.4.0-dev.2155+2ccc5085"
+    "@fedify/fedify": "2.4.0-dev.2157+b76e5888",
+    "@fedify/relay": "2.4.0-dev.2157+b76e5888",
+    "@fedify/sqlite": "2.4.0-dev.2157+b76e5888",
+    "@fedify/vocab": "2.4.0-dev.2157+b76e5888",
+    "@fedify/init": "2.4.0-dev.2157+b76e5888",
+    "@fedify/vocab-runtime": "2.4.0-dev.2157+b76e5888",
+    "@fedify/webfinger": "2.4.0-dev.2157+b76e5888",
+    "@fedify/vocab-tools": "2.4.0-dev.2157+b76e5888"
   },
   "devDependencies": {
     "@types/bun": "^1.2.23",
     "@types/node": "^24.12.2",
     "@types/pngjs": "^6.0.5",
     "tsdown": "^0.22.0",
-    "typescript": "^6.0.0"
+    "typescript": "^6.0.0",
+    "@fedify/fixture": "2.0.0"
   },
   "scripts": {
     "build:self": "tsdown",