@fedify/cli 2.0.6 → 2.1.0

package/README.md

@@ -52,7 +52,7 @@ command:
 # Linux/macOS
 deno install \
   -A \
-  --unstable-fs --unstable-kv --unstable-temporal \
+  --unstable-fs --unstable-kv \
   -n fedify \
   jsr:@fedify/cli
 ~~~~
@@ -61,11 +61,14 @@ deno install \
 # Windows
 deno install `
   -A `
-  --unstable-fs --unstable-kv --unstable-temporal `
+  --unstable-fs --unstable-kv `
   -n fedify `
   jsr:@fedify/cli
 ~~~~
 
+On Deno versions earlier than 2.7.0, add `--unstable-temporal` to the install
+command above.
+
 [Deno]: https://deno.com/
 
 ### Downloading the executable

package/dist/config.js

@@ -6,7 +6,7 @@ import { printError } from "@optique/run";
 import { readFileSync } from "node:fs";
 import { parse } from "smol-toml";
 import { createConfigContext } from "@optique/config";
-import { array, boolean, number, object as object$1, optional as optional$1, picklist, string as string$1 } from "valibot";
+import { array, boolean, check, forward, integer as integer$1, minValue, number, object as object$1, optional as optional$1, picklist, pipe, string as string$1 } from "valibot";
 
 //#region src/config.ts
 /**
@@ -19,11 +19,22 @@ const webfingerSchema = object$1({
 /**
 * Schema for the lookup command configuration.
 */
-const lookupSchema = object$1({
+const lookupSchema = pipe(object$1({
 	authorizedFetch: optional$1(boolean()),
 	firstKnock: optional$1(picklist(["draft-cavage-http-signatures-12", "rfc9421"])),
+	allowPrivateAddress: optional$1(boolean()),
 	traverse: optional$1(boolean()),
+	recurse: optional$1(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$1(pipe(number(), integer$1(), minValue(1))),
 	suppressErrors: optional$1(boolean()),
+	reverse: optional$1(boolean()),
 	defaultFormat: optional$1(picklist([
 		"default",
 		"raw",
@@ -32,7 +43,7 @@ const lookupSchema = object$1({
 	])),
 	separator: optional$1(string$1()),
 	timeout: optional$1(number())
-});
+}), forward(check((input) => !(input.traverse === true && input.recurse != null), "lookup.traverse and lookup.recurse cannot be used together."), ["recurse"]), forward(check((input) => input.recurse != null || input.recurseDepth == null, "lookup.recurseDepth requires lookup.recurse."), ["recurseDepth"]));
 /**
 * Schema for the inbox command configuration.
 */

package/dist/deno.js

@@ -3,7 +3,7 @@
     
 //#region deno.json
 var name = "@fedify/cli";
-var version = "2.0.6";
+var version = "2.1.0";
 var license = "MIT";
 var exports = "./src/mod.ts";
 var imports = {

package/dist/docloader.js

@@ -7,11 +7,26 @@ import { getKvStore } from "#kv";
 
 //#region src/docloader.ts
 const documentLoaders = {};
-async function getDocumentLoader$1({ userAgent } = {}) {
-	if (documentLoaders[userAgent ?? ""]) return documentLoaders[userAgent ?? ""];
+/**
+* Returns a cache prefix that separates document-loader entries by user agent
+* and private-address policy.
+*/
+function getDocumentLoaderCachePrefix(userAgent, allowPrivateAddress) {
+	return [
+		"_fedify",
+		"remoteDocument",
+		"cli",
+		userAgent ?? "",
+		allowPrivateAddress ? "allow-private" : "deny-private"
+	];
+}
+async function getDocumentLoader$1({ userAgent, allowPrivateAddress = false } = {}) {
+	const cacheKey = `${userAgent ?? ""}:${allowPrivateAddress}`;
+	if (documentLoaders[cacheKey]) return documentLoaders[cacheKey];
 	const kv = await getKvStore();
-	return documentLoaders[userAgent ?? ""] = kvCache({
+	return documentLoaders[cacheKey] = kvCache({
 		kv,
+		prefix: getDocumentLoaderCachePrefix(userAgent, allowPrivateAddress),
 		rules: [
 			[new URLPattern({
 				protocol: "http{s}?",
@@ -39,7 +54,7 @@ async function getDocumentLoader$1({ userAgent } = {}) {
 			}), { seconds: 0 }]
 		],
 		loader: getDocumentLoader({
-			allowPrivateAddress: true,
+			allowPrivateAddress,
 			userAgent
 		})
 	});

package/dist/imagerenderer.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import fs from "node:fs/promises";
 import os from "node:os";
 import process from "node:process";
+import { validatePublicUrl } from "@fedify/vocab-runtime";
 import { encodeBase64 } from "byte-encodings/base64";
 
 //#region src/imagerenderer.ts
@@ -18,6 +19,22 @@ const KITTY_IDENTIFIERS = [
 	"st",
 	"ghostty"
 ];
+function getExtensionFromContentType(contentType) {
+	const mime = contentType?.split(";")[0]?.trim().toLowerCase() ?? "";
+	switch (mime) {
+		case "image/jpeg":
+		case "image/jpg": return "jpg";
+		case "image/png": return "png";
+		case "image/gif": return "gif";
+		case "image/webp": return "webp";
+		case "image/avif": return "avif";
+		case "image/bmp": return "bmp";
+		case "image/svg+xml": return "svg";
+		default:
+			if (mime.startsWith("image/")) return mime.slice(6);
+			return "jpg";
+	}
+}
 function detectTerminalCapabilities() {
 	const termProgram = (process.env.TERM_PROGRAM || "").toLowerCase();
 	if (KITTY_IDENTIFIERS.includes(termProgram)) return "kitty";
@@ -70,9 +87,37 @@ async function renderImageITerm2(imagePath) {
 }
 async function downloadImage(url) {
 	try {
-		const response = await fetch(url);
+		let targetUrl = url;
+		let response = null;
+		for (let redirectCount = 0; redirectCount < 10; redirectCount++) {
+			await validatePublicUrl(targetUrl);
+			response = await fetch(targetUrl, { redirect: "manual" });
+			if (response.status === 301 || response.status === 302 || response.status === 303 || response.status === 307 || response.status === 308) {
+				const location = response.headers.get("location");
+				if (location == null) {
+					await response.body?.cancel();
+					return null;
+				}
+				await response.body?.cancel();
+				targetUrl = new URL(location, targetUrl).href;
+				continue;
+			}
+			break;
+		}
+		if (response == null) return null;
+		if (!response.ok) {
+			await response.body?.cancel();
+			return null;
+		}
 		const imageData = new Uint8Array(await response.arrayBuffer());
-		const extension = new URL(url).pathname.split(".").pop() || "jpg";
+		const pathname = new URL(targetUrl).pathname;
+		const lowerPathname = pathname.toLowerCase();
+		if (lowerPathname.includes("%2f") || lowerPathname.includes("%5c") || lowerPathname.includes("..")) return null;
+		const pathSegments = pathname.split("/").filter((segment) => segment !== "");
+		const filename = pathSegments[pathSegments.length - 1] ?? "";
+		const extension = filename.includes(".") ? path.extname(filename).slice(1) : getExtensionFromContentType(response.headers.get("content-type"));
+		if (extension.length < 1) return null;
+		if (extension.includes("/") || extension.includes("\\") || extension.includes("..")) return null;
 		const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "fedify"));
 		const tempPath = path.join(tempDir, `image.${extension}`);
 		await fs.writeFile(tempPath, imageData);

package/dist/lookup.js

@@ -9,14 +9,15 @@ import { spawnTemporaryServer } from "./tempserver.js";
 import { colorEnabled, colors, formatObject } from "./utils.js";
 import { renderImages } from "./imagerenderer.js";
 import process from "node:process";
-import { argument, choice, command, constant, flag, float, map, merge, message, multiple, object, option, optionNames, optional, or, string, withDefault } from "@optique/core";
-import { path, print, printError } from "@optique/run";
+import { argument, choice, command, constant, flag, float, integer, map, merge, message, multiple, object, option, optionNames, optional, or, string, withDefault } from "@optique/core";
+import { path, printError } from "@optique/run";
 import { createWriteStream } from "node:fs";
 import { bindConfig } from "@optique/config";
 import { generateCryptoKeyPair, getAuthenticatedDocumentLoader, respondWithObject } from "@fedify/fedify";
 import { Application, Collection, CryptographicKey, Object as Object$1, lookupObject, traverseCollection } from "@fedify/vocab";
 import { getLogger } from "@logtape/logtape";
 import ora from "ora";
+import { UrlError } from "@fedify/vocab-runtime";
 
 //#region src/lookup.ts
 const logger = getLogger([
@@ -24,6 +25,28 @@ const logger = getLogger([
 	"cli",
 	"lookup"
 ]);
+const IN_REPLY_TO_IRI = "https://www.w3.org/ns/activitystreams#inReplyTo";
+const QUOTE_URL_IRI = "https://www.w3.org/ns/activitystreams#quoteUrl";
+const MISSKEY_QUOTE_IRI = "https://misskey-hub.net/ns#_misskey_quote";
+const FEDIBIRD_QUOTE_IRI = "http://fedibird.com/ns#quoteUri";
+const recurseProperties = [
+	"replyTarget",
+	"quoteUrl",
+	IN_REPLY_TO_IRI,
+	QUOTE_URL_IRI,
+	MISSKEY_QUOTE_IRI,
+	FEDIBIRD_QUOTE_IRI
+];
+const suppressErrorsOption = bindConfig(flag("-S", "--suppress-errors", { description: message`Suppress partial errors during traversal or recursion.` }), {
+	context: configContext,
+	key: (config) => config.lookup?.suppressErrors ?? false,
+	default: false
+});
+const allowPrivateAddressOption = bindConfig(flag("-p", "--allow-private-address", { description: message`Allow private IP addresses for explicit lookup/traverse requests.` }), {
+	context: configContext,
+	key: (config) => config.lookup?.allowPrivateAddress ?? false,
+	default: false
+});
 const authorizedFetchOption = withDefault(object("Authorized fetch options", {
 	authorizedFetch: bindConfig(map(flag("-a", "--authorized-fetch", { description: message`Sign the request with an one-time key.` }), () => true), {
 		context: configContext,
@@ -40,25 +63,50 @@ const authorizedFetchOption = withDefault(object("Authorized fetch options", {
 	firstKnock: void 0,
 	tunnelService: void 0
 });
-const traverseOption = object("Traverse options", {
+const lookupModeOption = withDefault(or(object("Recurse options", {
+	traverse: constant(false),
+	recurse: bindConfig(option("--recurse", choice(recurseProperties, { metavar: "PROPERTY" }), { description: message`Recursively follow a relationship property.` }), {
+		context: configContext,
+		key: (config) => config.lookup?.recurse
+	}),
+	recurseDepth: withDefault(bindConfig(option("--recurse-depth", integer({
+		min: 1,
+		metavar: "DEPTH"
+	}), { description: message`Maximum recursion depth for ${optionNames(["--recurse"])}.` }), {
+		context: configContext,
+		key: (config) => config.lookup?.recurseDepth
+	}), 20),
+	suppressErrors: suppressErrorsOption
+}), object("Traverse options", {
 	traverse: bindConfig(flag("-t", "--traverse", { description: message`Traverse the given collection(s) to fetch all items.` }), {
 		context: configContext,
 		key: (config) => config.lookup?.traverse ?? false,
 		default: false
 	}),
-	suppressErrors: bindConfig(flag("-S", "--suppress-errors", { description: message`Suppress partial errors while traversing the collection.` }), {
+	recurse: constant(void 0),
+	recurseDepth: constant(void 0),
+	suppressErrors: suppressErrorsOption
+})), {
+	traverse: false,
+	recurse: void 0,
+	recurseDepth: void 0,
+	suppressErrors: false
+});
+const lookupCommand = command("lookup", merge(object({ command: constant("lookup") }), lookupModeOption, authorizedFetchOption, merge("Network options", userAgentOption, object({
+	allowPrivateAddress: allowPrivateAddressOption,
+	timeout: optional(bindConfig(option("-T", "--timeout", float({
+		min: 0,
+		metavar: "SECONDS"
+	}), { description: message`Set timeout for network requests in seconds.` }), {
 		context: configContext,
-		key: (config) => config.lookup?.suppressErrors ?? false,
+		key: (config) => config.lookup?.timeout
+	}))
+})), object("Arguments", { urls: multiple(argument(string({ metavar: "URL_OR_HANDLE" }), { description: message`One or more URLs or handles to look up.` }), { min: 1 }) }), object("Output options", {
+	reverse: bindConfig(flag("--reverse", { description: message`Reverse the output order of fetched objects or items.` }), {
+		context: configContext,
+		key: (config) => config.lookup?.reverse ?? false,
 		default: false
-	})
-});
-const lookupCommand = command("lookup", merge(object({ command: constant("lookup") }), traverseOption, authorizedFetchOption, merge("Network options", userAgentOption, object({ timeout: optional(bindConfig(option("-T", "--timeout", float({
-	min: 0,
-	metavar: "SECONDS"
-}), { description: message`Set timeout for network requests in seconds.` }), {
-	context: configContext,
-	key: (config) => config.lookup?.timeout
-})) })), object("Arguments", { urls: multiple(argument(string({ metavar: "URL_OR_HANDLE" }), { description: message`One or more URLs or handles to look up.` }), { min: 1 }) }), object("Output options", {
+	}),
 	format: bindConfig(optional(or(map(flag("-r", "--raw", { description: message`Print the fetched JSON-LD document as is.` }), () => "raw"), map(flag("-C", "--compact", { description: message`Compact the fetched JSON-LD document.` }), () => "compact"), map(flag("-e", "--expand", { description: message`Expand the fetched JSON-LD document.` }), () => "expand"))), {
 		context: configContext,
 		key: (config) => config.lookup?.defaultFormat ?? "default",
@@ -87,6 +135,55 @@ var TimeoutError = class extends Error {
 		this.name = "TimeoutError";
 	}
 };
+/**
+* Error thrown when a recursive lookup target cannot be fetched.
+*/
+var RecursiveLookupError = class extends Error {
+	target;
+	constructor(target) {
+		super(`Failed to recursively fetch object: ${target}`);
+		this.name = "RecursiveLookupError";
+		this.target = target;
+	}
+};
+function writeToStream(stream, chunk) {
+	return new Promise((resolve, reject) => {
+		const onError = (error) => {
+			stream.off("error", onError);
+			reject(error);
+		};
+		stream.once("error", onError);
+		try {
+			stream.write(chunk, (error) => {
+				stream.off("error", onError);
+				if (error != null) reject(error);
+				else resolve();
+			});
+		} catch (error) {
+			stream.off("error", onError);
+			reject(error instanceof Error ? error : new Error(String(error)));
+		}
+	});
+}
+function endWritableStream(stream) {
+	return new Promise((resolve, reject) => {
+		const onError = (error) => {
+			stream.off("error", onError);
+			reject(error);
+		};
+		stream.once("error", onError);
+		try {
+			stream.end((error) => {
+				stream.off("error", onError);
+				if (error != null) reject(error);
+				else resolve();
+			});
+		} catch (error) {
+			stream.off("error", onError);
+			reject(error instanceof Error ? error : new Error(String(error)));
+		}
+	});
+}
 async function findAllImages(obj) {
 	const result = [];
 	const icon = await obj.getIcon();
@@ -95,8 +192,9 @@ async function findAllImages(obj) {
 	if (image && image.url instanceof URL) result.push(image.url);
 	return result;
 }
-async function writeObjectToStream(object$1, outputPath, format, contextLoader) {
-	const stream = outputPath ? createWriteStream(outputPath) : process.stdout;
+async function writeObjectToStream(object$1, outputPath, format, contextLoader, stream) {
+	const localStream = stream ?? (outputPath ? createWriteStream(outputPath) : process.stdout);
+	const localFileStream = stream == null && outputPath != null ? localStream : void 0;
 	let content;
 	let json = true;
 	let imageUrls = [];
@@ -117,13 +215,37 @@ async function writeObjectToStream(object$1, outputPath, format, contextLoader)
 		content = object$1;
 		json = false;
 	}
-	const enableColors = colorEnabled && outputPath === void 0;
+	const enableColors = colorEnabled && localStream === process.stdout;
 	content = formatObject(content, enableColors, json);
 	const encoder = new TextEncoder();
 	const bytes = encoder.encode(content + "\n");
-	stream.write(bytes);
+	await writeToStream(localStream, bytes);
+	if (localFileStream != null) await endWritableStream(localFileStream);
 	if (object$1 instanceof Object$1) imageUrls = await findAllImages(object$1);
-	if (!outputPath && imageUrls.length > 0) await renderImages(imageUrls);
+	if (localStream === process.stdout && imageUrls.length > 0) await renderImages(imageUrls);
+}
+async function closeWriteStream(stream) {
+	if (stream == null) return;
+	await endWritableStream(stream);
+}
+async function writeSeparator(separator, stream) {
+	await writeToStream(stream ?? process.stdout, `${separator}\n`);
+}
+function toPresentationOrder(items, reverse) {
+	if (reverse) return [...items].reverse();
+	return items;
+}
+async function collectAsyncItems(iterable) {
+	const items = [];
+	try {
+		for await (const item of iterable) items.push(item);
+		return { items };
+	} catch (error) {
+		return {
+			items,
+			error
+		};
+	}
 }
 const signalTimers = /* @__PURE__ */ new WeakMap();
 function createTimeoutSignal(timeoutSeconds) {
@@ -158,22 +280,152 @@ function handleTimeoutError(spinner, timeoutSeconds, url) {
 	spinner.fail(`Request timed out after ${timeoutSeconds} seconds${urlText}.`);
 	printError(message`Try increasing the timeout with -T/--timeout option or check network connectivity.`);
 }
-async function runLookup(command$1) {
+function isPrivateAddressError(error) {
+	const errorMessage = error instanceof Error ? error.message : String(error);
+	const lowerMessage = errorMessage.toLowerCase();
+	if (error instanceof UrlError) return 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 getLookupFailureHint(error, options = {}) {
+	if (isPrivateAddressError(error)) return options.recursive ? "recursive-private-address" : "private-address";
+	return "authorized-fetch";
+}
+function shouldPrintLookupFailureHint(authLoader, hint) {
+	return hint !== "authorized-fetch" || authLoader == null;
+}
+function shouldSuggestSuppressErrorsForLookupFailure(authLoader, hint) {
+	return authLoader != null && hint === "authorized-fetch";
+}
+function printLookupFailureHint(authLoader, error, options = {}) {
+	const hint = getLookupFailureHint(error, options);
+	if (!shouldPrintLookupFailureHint(authLoader, hint)) return;
+	switch (hint) {
+		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.
+*/
+function getRecursiveTargetId(object$1, recurseProperty) {
+	switch (recurseProperty) {
+		case "replyTarget":
+		case IN_REPLY_TO_IRI: return object$1.replyTargetId;
+		case "quoteUrl":
+		case QUOTE_URL_IRI:
+		case MISSKEY_QUOTE_IRI:
+		case FEDIBIRD_QUOTE_IRI: {
+			const quoteUrl = object$1.quoteUrl;
+			return quoteUrl instanceof URL ? quoteUrl : null;
+		}
+		default: return null;
+	}
+}
+/**
+* Collects recursively linked objects up to a depth limit.
+*/
+async function collectRecursiveObjects(initialObject, recurseProperty, recurseDepth, lookup, options) {
+	const visited = options.visited ?? /* @__PURE__ */ new Set();
+	const results = [];
+	let current = initialObject;
+	if (current.id != null) visited.add(current.id.href);
+	for (let depth = 0; depth < recurseDepth; depth++) {
+		const targetId = getRecursiveTargetId(current, recurseProperty);
+		if (targetId == null) break;
+		const target = targetId.href;
+		if (visited.has(target)) break;
+		let next;
+		try {
+			next = await lookup(target);
+		} catch (error) {
+			if (options.suppressErrors) {
+				logger.debug("Failed to recursively fetch object {target}, but suppressing error: {error}", {
+					target,
+					error
+				});
+				break;
+			}
+			throw error;
+		}
+		if (next == null) {
+			if (options.suppressErrors) {
+				logger.debug("Failed to recursively fetch object {target} (not found), but suppressing error.", { target });
+				break;
+			}
+			throw new RecursiveLookupError(target);
+		}
+		results.push(next);
+		visited.add(target);
+		if (next.id != null) visited.add(next.id.href);
+		current = next;
+	}
+	return results;
+}
+async function runLookup(command$1, deps = {}) {
+	const effectiveDeps = {
+		lookupObject,
+		traverseCollection,
+		exit: (code) => process.exit(code),
+		...deps
+	};
 	if (command$1.urls.length < 1) {
 		printError(message`At least one URL or actor handle must be provided.`);
-		process.exit(1);
+		effectiveDeps.exit(1);
 	}
 	if (command$1.debug) await configureLogging();
 	const spinner = ora({
-		text: `Looking up the ${command$1.traverse ? "collection" : command$1.urls.length > 1 ? "objects" : "object"}...`,
+		text: `Looking up the ${command$1.recurse != null ? "object chain" : command$1.traverse ? "collection" : command$1.urls.length > 1 ? "objects" : "object"}...`,
 		discardStdin: false
 	}).start();
 	let server = void 0;
-	const baseDocumentLoader = await getDocumentLoader({ userAgent: command$1.userAgent });
+	const baseDocumentLoader = await getDocumentLoader({
+		userAgent: command$1.userAgent,
+		allowPrivateAddress: command$1.allowPrivateAddress
+	});
 	const documentLoader = wrapDocumentLoaderWithTimeout(baseDocumentLoader, command$1.timeout);
-	const baseContextLoader = await getContextLoader({ userAgent: command$1.userAgent });
+	const baseContextLoader = await getContextLoader({
+		userAgent: command$1.userAgent,
+		allowPrivateAddress: command$1.allowPrivateAddress
+	});
 	const contextLoader = wrapDocumentLoaderWithTimeout(baseContextLoader, command$1.timeout);
 	let authLoader = void 0;
+	let authIdentity = void 0;
+	let outputStream;
+	let outputStreamError;
+	const getOutputStream = () => {
+		if (command$1.output == null) return void 0;
+		if (outputStream == null) {
+			outputStream = createWriteStream(command$1.output);
+			outputStream.once("error", (error) => {
+				outputStreamError = error;
+			});
+		}
+		if (outputStreamError != null) throw outputStreamError;
+		return outputStream;
+	};
+	const finalizeAndExit = async (code) => {
+		let cleanupFailed = false;
+		try {
+			await closeWriteStream(outputStream);
+		} catch (error) {
+			cleanupFailed = true;
+			logger.error("Failed to close output stream during shutdown: {error}", { error });
+		}
+		try {
+			await server?.close();
+		} catch (error) {
+			cleanupFailed = true;
+			logger.error("Failed to close temporary server during shutdown: {error}", { error });
+		}
+		effectiveDeps.exit(cleanupFailed && code === 0 ? 1 : code);
+	};
 	if (command$1.authorizedFetch) {
 		spinner.text = "Generating a one-time key pair...";
 		const key = await generateCryptoKeyPair();
@@ -205,26 +457,174 @@ async function runLookup(command$1) {
 				outbox: new URL("/outbox", serverUrl)
 			}), { contextLoader });
 		}, { service: command$1.tunnelService });
-		const baseAuthLoader = getAuthenticatedDocumentLoader({
+		authIdentity = {
 			keyId: new URL("#main-key", server.url),
 			privateKey: key.privateKey
-		}, { specDeterminer: {
-			determineSpec() {
-				return command$1.firstKnock;
-			},
-			rememberSpec() {}
-		} });
+		};
+		const baseAuthLoader = getAuthenticatedDocumentLoader(authIdentity, {
+			allowPrivateAddress: command$1.allowPrivateAddress,
+			userAgent: command$1.userAgent,
+			specDeterminer: {
+				determineSpec() {
+					return command$1.firstKnock;
+				},
+				rememberSpec() {}
+			}
+		});
 		authLoader = wrapDocumentLoaderWithTimeout(baseAuthLoader, command$1.timeout);
 	}
-	spinner.text = `Looking up the ${command$1.traverse ? "collection" : command$1.urls.length > 1 ? "objects" : "object"}...`;
+	spinner.text = `Looking up the ${command$1.recurse != null ? "object chain" : command$1.traverse ? "collection" : command$1.urls.length > 1 ? "objects" : "object"}...`;
+	if (command$1.recurse != null) {
+		const recursiveBaseDocumentLoader = await getDocumentLoader({
+			userAgent: command$1.userAgent,
+			allowPrivateAddress: false
+		});
+		const recursiveDocumentLoader = wrapDocumentLoaderWithTimeout(recursiveBaseDocumentLoader, command$1.timeout);
+		const recursiveBaseContextLoader = await getContextLoader({
+			userAgent: command$1.userAgent,
+			allowPrivateAddress: false
+		});
+		const recursiveContextLoader = wrapDocumentLoaderWithTimeout(recursiveBaseContextLoader, command$1.timeout);
+		const recursiveAuthLoader = command$1.authorizedFetch && authIdentity != null ? wrapDocumentLoaderWithTimeout(getAuthenticatedDocumentLoader(authIdentity, {
+			allowPrivateAddress: false,
+			userAgent: command$1.userAgent,
+			specDeterminer: {
+				determineSpec() {
+					return command$1.firstKnock;
+				},
+				rememberSpec() {}
+			}
+		}), command$1.timeout) : void 0;
+		const initialLookupDocumentLoader = authLoader ?? documentLoader;
+		const recursiveLookupDocumentLoader = recursiveAuthLoader ?? recursiveDocumentLoader;
+		let totalObjects = 0;
+		const recurseDepth = command$1.recurseDepth;
+		for (let urlIndex = 0; urlIndex < command$1.urls.length; urlIndex++) {
+			const visited = /* @__PURE__ */ new Set();
+			const url = command$1.urls[urlIndex];
+			if (urlIndex > 0) spinner.text = `Looking up object chain ${urlIndex + 1}/${command$1.urls.length}...`;
+			let current = null;
+			try {
+				current = await effectiveDeps.lookupObject(url, {
+					documentLoader: initialLookupDocumentLoader,
+					contextLoader,
+					userAgent: command$1.userAgent
+				});
+			} catch (error) {
+				if (error instanceof TimeoutError) handleTimeoutError(spinner, command$1.timeout, url);
+				else {
+					spinner.fail(`Failed to fetch object: ${colors.red(url)}.`);
+					printLookupFailureHint(authLoader, error);
+				}
+				await finalizeAndExit(1);
+				return;
+			}
+			if (current == null) {
+				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.`);
+				await finalizeAndExit(1);
+				return;
+			}
+			visited.add(url);
+			if (current.id != null) visited.add(current.id.href);
+			if (!command$1.reverse) try {
+				if (totalObjects > 0) await writeSeparator(command$1.separator, getOutputStream());
+				await writeObjectToStream(current, command$1.output, command$1.format, contextLoader, getOutputStream());
+				totalObjects++;
+			} catch (error) {
+				logger.error("Failed to write lookup output: {error}", { error });
+				spinner.fail("Failed to write output.");
+				await finalizeAndExit(1);
+				return;
+			}
+			let chain = [];
+			try {
+				chain = await collectRecursiveObjects(current, command$1.recurse, recurseDepth, (target) => effectiveDeps.lookupObject(target, {
+					documentLoader: recursiveLookupDocumentLoader,
+					contextLoader: recursiveContextLoader,
+					userAgent: command$1.userAgent
+				}), {
+					suppressErrors: command$1.suppressErrors,
+					visited
+				});
+			} catch (error) {
+				if (command$1.reverse) try {
+					if (totalObjects > 0) await writeSeparator(command$1.separator, getOutputStream());
+					await writeObjectToStream(current, command$1.output, command$1.format, contextLoader, getOutputStream());
+					totalObjects++;
+				} catch (writeError) {
+					logger.error("Failed to write lookup output: {error}", { error: writeError });
+					spinner.fail("Failed to write output.");
+					await finalizeAndExit(1);
+					return;
+				}
+				logger.error("Failed to recursively fetch an object in chain: {error}", { error });
+				if (error instanceof TimeoutError) handleTimeoutError(spinner, command$1.timeout);
+				else if (error instanceof RecursiveLookupError) {
+					spinner.fail(`Failed to recursively fetch object: ${colors.red(error.target)}.`);
+					if (authLoader == null) printError(message`It may be a private object.  Try with -a/--authorized-fetch.`);
+				} else {
+					spinner.fail("Failed to recursively fetch object.");
+					const hint = getLookupFailureHint(error, { recursive: true });
+					if (shouldSuggestSuppressErrorsForLookupFailure(authLoader, hint)) printError(message`Use the -S/--suppress-errors option to suppress partial errors.`);
+					else printLookupFailureHint(authLoader, error, { recursive: true });
+				}
+				await finalizeAndExit(1);
+				return;
+			}
+			if (command$1.reverse) {
+				const chainEntries = [{
+					object: current,
+					objectContextLoader: contextLoader
+				}, ...chain.map((next) => ({
+					object: next,
+					objectContextLoader: recursiveContextLoader
+				}))];
+				for (let chainIndex = chainEntries.length - 1; chainIndex >= 0; chainIndex--) {
+					const entry = chainEntries[chainIndex];
+					try {
+						if (totalObjects > 0 || chainIndex < chainEntries.length - 1) await writeSeparator(command$1.separator, getOutputStream());
+						await writeObjectToStream(entry.object, command$1.output, command$1.format, entry.objectContextLoader, getOutputStream());
+						totalObjects++;
+					} catch (error) {
+						logger.error("Failed to write lookup output: {error}", { error });
+						spinner.fail("Failed to write output.");
+						await finalizeAndExit(1);
+						return;
+					}
+				}
+			} else {
+				const chainEntries = chain.map((next) => ({
+					object: next,
+					objectContextLoader: recursiveContextLoader
+				}));
+				for (let chainIndex = 0; chainIndex < chainEntries.length; chainIndex++) {
+					const entry = chainEntries[chainIndex];
+					try {
+						if (totalObjects > 0 || chainIndex > 0) await writeSeparator(command$1.separator, getOutputStream());
+						await writeObjectToStream(entry.object, command$1.output, command$1.format, entry.objectContextLoader, getOutputStream());
+						totalObjects++;
+					} catch (error) {
+						logger.error("Failed to write lookup output: {error}", { error });
+						spinner.fail("Failed to write output.");
+						await finalizeAndExit(1);
+						return;
+					}
+				}
+			}
+		}
+		spinner.succeed("Successfully fetched all reachable objects in the chain.");
+		await finalizeAndExit(0);
+		return;
+	}
 	if (command$1.traverse) {
 		let totalItems = 0;
 		for (let urlIndex = 0; urlIndex < command$1.urls.length; urlIndex++) {
 			const url = command$1.urls[urlIndex];
 			if (urlIndex > 0) spinner.text = `Looking up collection ${urlIndex + 1}/${command$1.urls.length}...`;
-			let collection;
+			let collection = null;
 			try {
-				collection = await lookupObject(url, {
+				collection = await effectiveDeps.lookupObject(url, {
 					documentLoader: authLoader ?? documentLoader,
 					contextLoader,
 					userAgent: command$1.userAgent
@@ -233,33 +633,64 @@ async function runLookup(command$1) {
 				if (error instanceof TimeoutError) handleTimeoutError(spinner, command$1.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 server?.close();
-				process.exit(1);
+				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 -a/--authorized-fetch.`);
-				await server?.close();
-				process.exit(1);
+				await finalizeAndExit(1);
+				return;
 			}
 			if (!(collection instanceof Collection)) {
 				spinner.fail(`Not a collection: ${colors.red(url)}.  The -t/--traverse option requires a collection.`);
-				await server?.close();
-				process.exit(1);
+				await finalizeAndExit(1);
+				return;
 			}
 			spinner.succeed(`Fetched collection: ${colors.green(url)}.`);
 			try {
-				let collectionItems = 0;
-				for await (const item of traverseCollection(collection, {
+				if (command$1.reverse) {
+					const { items: traversedItems, error: traversalError } = await collectAsyncItems(effectiveDeps.traverseCollection(collection, {
+						documentLoader: authLoader ?? documentLoader,
+						contextLoader,
+						suppressError: command$1.suppressErrors
+					}));
+					for (let index = traversedItems.length - 1; index >= 0; index--) {
+						const item = traversedItems[index];
+						try {
+							if (totalItems > 0) await writeSeparator(command$1.separator, getOutputStream());
+							await writeObjectToStream(item, command$1.output, command$1.format, contextLoader, getOutputStream());
+						} catch (error) {
+							logger.error("Failed to write output for {url}: {error}", {
+								url,
+								error
+							});
+							spinner.fail(`Failed to write output for: ${colors.red(url)}.`);
+							await finalizeAndExit(1);
+							return;
+						}
+						totalItems++;
+					}
+					if (traversalError != null) throw traversalError;
+				} else for await (const item of effectiveDeps.traverseCollection(collection, {
 					documentLoader: authLoader ?? documentLoader,
 					contextLoader,
 					suppressError: command$1.suppressErrors
 				})) {
-					if (!command$1.output && (totalItems > 0 || collectionItems > 0)) print(message`${command$1.separator}`);
-					await writeObjectToStream(item, command$1.output, command$1.format, contextLoader);
-					collectionItems++;
+					try {
+						if (totalItems > 0) await writeSeparator(command$1.separator, getOutputStream());
+						await writeObjectToStream(item, command$1.output, command$1.format, contextLoader, getOutputStream());
+					} catch (error) {
+						logger.error("Failed to write output for {url}: {error}", {
+							url,
+							error
+						});
+						spinner.fail(`Failed to write output for: ${colors.red(url)}.`);
+						await finalizeAndExit(1);
+						return;
+					}
 					totalItems++;
 				}
 			} catch (error) {
@@ -270,19 +701,20 @@ async function runLookup(command$1) {
 				if (error instanceof TimeoutError) handleTimeoutError(spinner, command$1.timeout, url);
 				else {
 					spinner.fail(`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.`);
-					else printError(message`Use the -S/--suppress-errors option to suppress partial errors.`);
+					const hint = getLookupFailureHint(error);
+					if (shouldSuggestSuppressErrorsForLookupFailure(authLoader, hint)) printError(message`Use the -S/--suppress-errors option to suppress partial errors.`);
+					else printLookupFailureHint(authLoader, error);
 				}
-				await server?.close();
-				process.exit(1);
+				await finalizeAndExit(1);
+				return;
 			}
 		}
 		spinner.succeed("Successfully fetched all items in the collection.");
-		await server?.close();
-		process.exit(0);
+		await finalizeAndExit(0);
+		return;
 	}
 	const promises = [];
-	for (const url of command$1.urls) promises.push(lookupObject(url, {
+	for (const url of command$1.urls) promises.push(effectiveDeps.lookupObject(url, {
 		documentLoader: authLoader ?? documentLoader,
 		contextLoader,
 		userAgent: command$1.userAgent
@@ -290,33 +722,54 @@ async function runLookup(command$1) {
 		if (error instanceof TimeoutError) handleTimeoutError(spinner, command$1.timeout, url);
 		throw error;
 	}));
-	let objects;
+	let objects = [];
 	try {
 		objects = await Promise.all(promises);
 	} catch (_error) {
-		await server?.close();
-		process.exit(1);
+		await finalizeAndExit(1);
+		return;
 	}
 	spinner.stop();
 	let success = true;
-	let i = 0;
-	for (const obj of objects) {
+	let printedCount = 0;
+	const successfulObjects = [];
+	for (const [i, obj] of objects.entries()) {
 		const url = command$1.urls[i];
-		if (i > 0) print(message`${command$1.separator}`);
-		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 -a/--authorized-fetch.`);
 			success = false;
 		} else {
 			spinner.succeed(`Fetched object: ${colors.green(url)}`);
-			await writeObjectToStream(obj, command$1.output, command$1.format, contextLoader);
-			if (i < command$1.urls.length - 1) print(message`${command$1.separator}`);
+			successfulObjects.push(obj);
 		}
 	}
+	for (const obj of toPresentationOrder(successfulObjects, command$1.reverse)) {
+		try {
+			if (printedCount > 0) await writeSeparator(command$1.separator, getOutputStream());
+			await writeObjectToStream(obj, command$1.output, command$1.format, contextLoader, getOutputStream());
+		} catch (error) {
+			logger.error("Failed to write lookup output: {error}", { error });
+			spinner.fail("Failed to write output.");
+			await finalizeAndExit(1);
+			return;
+		}
+		printedCount++;
+	}
 	if (success) spinner.succeed(command$1.urls.length > 1 ? "Successfully fetched all objects." : "Successfully fetched the object.");
-	await server?.close();
-	if (!success) process.exit(1);
+	if (!success) {
+		await finalizeAndExit(1);
+		return;
+	}
+	try {
+		await closeWriteStream(outputStream);
+		await server?.close();
+	} catch (error) {
+		logger.error("Failed to finalize lookup resources: {error}", { error });
+		spinner.fail("Failed to finalize output.");
+		await finalizeAndExit(1);
+		return;
+	}
 	if (success && command$1.output) spinner.succeed(`Successfully wrote output to ${colors.green(command$1.output)}.`);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/cli",
-  "version": "2.0.6",
+  "version": "2.1.0",
   "type": "module",
   "files": [
     "README.md",
@@ -58,16 +58,16 @@
   },
   "dependencies": {
     "@fxts/core": "^1.20.0",
-    "@optique/config": "^0.10.6",
-    "@optique/core": "^0.10.6",
-    "@optique/run": "^0.10.6",
+    "@optique/config": "^0.10.7",
+    "@optique/core": "^0.10.7",
+    "@optique/run": "^0.10.7",
     "@hongminhee/localtunnel": "^0.3.0",
     "@inquirer/prompts": "^7.8.4",
     "@jimp/core": "^1.6.0",
     "@jimp/wasm-webp": "^1.6.0",
     "@js-temporal/polyfill": "^0.5.1",
-    "@logtape/file": "^2.0.0",
-    "@logtape/logtape": "^2.0.0",
+    "@logtape/file": "^2.0.5",
+    "@logtape/logtape": "^2.0.5",
     "@poppanator/http-constants": "^1.1.1",
     "byte-encodings": "^1.0.11",
     "chalk": "^5.6.2",
@@ -86,14 +86,14 @@
     "smol-toml": "^1.6.0",
     "srvx": "^0.8.7",
     "valibot": "^1.2.0",
-    "@fedify/fedify": "2.0.6",
-    "@fedify/init": "2.0.6",
-    "@fedify/relay": "2.0.6",
-    "@fedify/sqlite": "2.0.6",
-    "@fedify/vocab": "2.0.6",
-    "@fedify/vocab-runtime": "2.0.6",
-    "@fedify/vocab-tools": "2.0.6",
-    "@fedify/webfinger": "2.0.6"
+    "@fedify/fedify": "2.1.0",
+    "@fedify/init": "2.1.0",
+    "@fedify/vocab-runtime": "2.1.0",
+    "@fedify/sqlite": "2.1.0",
+    "@fedify/vocab-tools": "2.1.0",
+    "@fedify/vocab": "2.1.0",
+    "@fedify/webfinger": "2.1.0",
+    "@fedify/relay": "2.1.0"
   },
   "devDependencies": {
     "@types/bun": "^1.2.23",