@feralfile/cli 2.2.1 → 2.2.2

package/dist/index.js

@@ -9,7 +9,15 @@ process.on('warning', (warning) => {
     console.warn(warning.name + ': ' + warning.message);
 });
 require("dotenv/config");
+const net_1 = require("net");
 const commander_1 = require("commander");
+// Node's happy-eyeballs gives each address-family connect attempt 250 ms by
+// default. That is shorter than a single round trip to a far-away API host
+// (e.g. api.raster.art from Asia is ~250 ms RTT), so on networks with broken
+// IPv6 the IPv4 attempt gets cut off mid-handshake, the IPv6 fallback has no
+// route, and fetch fails or stalls intermittently (#97). 2.5 s per attempt is
+// still fast-failing but no longer races the speed of light.
+(0, net_1.setDefaultAutoSelectFamilyAttemptTimeout)(2500);
 const fs_1 = require("fs");
 const path_1 = require("path");
 const setup_1 = require("./src/commands/setup");

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@feralfile/cli",
-    "version": "2.2.1",
+    "version": "2.2.2",
     "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
     "repository": {
         "type": "git",

package/dist/src/commands/find.js

@@ -168,6 +168,13 @@ async function runResolvedTarget(target, options) {
         return;
     }
     console.log(chalk_1.default.dim(`Indexing ${tokens.length} token${tokens.length === 1 ? '' : 's'} via FF indexer...`));
+    // Previously-unseen tokens make the indexer warm renditions by polling —
+    // minutes of wall time on a large series. Say so upfront (the --limit
+    // warming hint used to appear only after a failure) and render per-batch
+    // progress so a long index never reads as a hang.
+    if (tokens.length > 10) {
+        console.log(chalk_1.default.dim('  First-time tokens can take the indexer a while to warm; use `--limit 5` for a faster first pass.'));
+    }
     // Second positional arg on getNFTTokenInfoBatch is `duration` (DP-1 item
     // display seconds), not concurrency — concurrency is hardcoded inside.
     // Omit it for auto timing: video/audio items carry no duration and play
@@ -176,7 +183,14 @@ async function runResolvedTarget(target, options) {
         chain: t.chain,
         contractAddress: t.contract,
         tokenId: t.tokenId,
-    })));
+    })), undefined, 
+    // Unconditional: suppressing the done===total call meant a one-batch
+    // index (including the recommended --limit 5 warm-up) printed nothing
+    // and multi-batch runs never showed completion. The final N/N line IS
+    // the "indexing finished" signal.
+    (done, total) => {
+        console.log(chalk_1.default.dim(`  ${done}/${total} tokens indexed...`));
+    });
     // FF-indexer bypass for Raster-minted tokens. The indexer doesn't carry
     // Raster's tokens, so it returns nothing — but Raster handed us each
     // token's playable `media.contentUrl`. Build DP-1 items straight from
@@ -223,10 +237,20 @@ async function resolveTarget(input, parsed, skipPrompt, limitOption) {
         return resolveCoords(parsed.coords);
     }
     if (parsed.kind === 'ff-url') {
-        if (parsed.urlKind === 'show') {
-            const target = await resolveTokenListInput(input, resolverLimitFromOption(limitOption), `Feral File show ${parsed.identifier}`);
+        // Shows and series both resolve through the source-resolver's Feral File
+        // site module, which enumerates exactly the tokens the page describes
+        // (series slug → /api/series → /api/artworks?seriesID). The old series
+        // path resolved ONE token via ff-marketplace and then asked Raster, which
+        // expands to the token's parent artwork — so a single-edition series page
+        // (e.g. a Display Edition) surprisingly built the sibling collection's
+        // full token list. A series URL means the user pointed at a specific
+        // series; build exactly that. Artwork URLs keep the coords→Raster path:
+        // a single-token page carries no series intent to preserve.
+        if (parsed.urlKind === 'show' || parsed.urlKind === 'series') {
+            const label = parsed.urlKind === 'show' ? 'show' : 'series';
+            const target = await resolveTokenListInput(input, resolverLimitFromOption(limitOption), `Feral File ${label} ${parsed.identifier}`);
             if (target === null) {
-                throw new Error(`Feral File: no supported tokens found for show "${parsed.identifier}".`);
+                throw new Error(`Feral File: no supported tokens found for ${label} "${parsed.identifier}".`);
             }
             return target;
         }
@@ -326,9 +350,25 @@ async function resolveTokenListInput(input, limit, fallbackTitle = 'Resolved sou
 /**
  * Resolve on-chain coords to a target. If Raster doesn't index this token,
  * fall back to single-token mode so we still build something playable.
+ *
+ * Raster being unreachable gets the same fallback: it only enriches the find
+ * (series enumeration, artist labels) — the coords in hand are enough to
+ * build a playable single-token playlist, and a network blip on one optional
+ * dependency must not kill the whole command (#97).
  */
 async function resolveCoords(coords) {
-    const summary = await (0, raster_client_1.resolveTokenToArtwork)(coords.chain, coords.contract, coords.tokenId);
+    let summary;
+    try {
+        summary = await (0, raster_client_1.resolveTokenToArtwork)(coords.chain, coords.contract, coords.tokenId);
+    }
+    catch (error) {
+        if (!(error instanceof raster_client_1.RasterUnreachableError)) {
+            throw error;
+        }
+        console.log(chalk_1.default.yellow(`  ${error.message}`));
+        console.log(chalk_1.default.dim('  Continuing without Raster — building a one-item playlist.'));
+        return { kind: 'single', coords };
+    }
     if (summary === null) {
         return { kind: 'single', coords };
     }

package/dist/src/utilities/ab-marketplace.js

@@ -46,6 +46,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveArtBlocksCollection = resolveArtBlocksCollection;
+const http_1 = require("./http");
 const logger = __importStar(require("../logger"));
 const user_agent_1 = require("./user-agent");
 const AB_GRAPHQL = 'https://artblocks-mainnet.hasura.app/v1/graphql';
@@ -64,7 +65,7 @@ async function resolveArtBlocksCollection(slug) {
         '    tokens(limit: 1, order_by: { invocation: asc }) { token_id }' +
         '  }' +
         '}';
-    const response = await fetch(AB_GRAPHQL, {
+    const response = await (0, http_1.fetchWithTimeout)(AB_GRAPHQL, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', 'User-Agent': user_agent_1.USER_AGENT },
         body: JSON.stringify({ query, variables: { slug } }),

package/dist/src/utilities/feed-fetcher.js

@@ -3,6 +3,7 @@
  * Utilities to fetch playlists from DP1 Feed API
  * API: https://github.com/display-protocol/dp1-feed
  */
+const { fetchWithTimeout } = require('./http');
 const chalk = require('chalk');
 const fuzzysort = require('fuzzysort');
 const { getFeedConfig } = require('../config');
@@ -42,7 +43,7 @@ async function fetchPlaylistsFromFeed(feedUrl, limit = 100) {
     try {
         // API has a maximum limit of 100
         const validLimit = Math.min(limit, 100);
-        const response = await fetch(`${feedUrl}/playlists?limit=${validLimit}&sort=-created`);
+        const response = await fetchWithTimeout(`${feedUrl}/playlists?limit=${validLimit}&sort=-created`);
         if (!response.ok) {
             console.log(chalk.yellow(`  Feed ${feedUrl} returned ${response.status}`));
             return {
@@ -97,7 +98,7 @@ async function fetchPlaylistsWithPagination(feedUrl, searchTerm, pageSize = 50,
         const remainingItems = maxItems - totalFetched;
         const currentLimit = Math.min(pageSize, remainingItems, 100);
         try {
-            const response = await fetch(`${feedUrl}/playlists?limit=${currentLimit}&offset=${offset}&sort=-created`);
+            const response = await fetchWithTimeout(`${feedUrl}/playlists?limit=${currentLimit}&offset=${offset}&sort=-created`);
             reachable = true;
             if (!response.ok) {
                 if (response.status === 404 || response.status === 400) {
@@ -297,7 +298,7 @@ async function getPlaylistById(idOrSlug, feedUrl = null) {
         // Try each feed URL until we find the playlist
         for (const url of feedUrls) {
             try {
-                const response = await fetch(`${url}/playlists/${idOrSlug}`);
+                const response = await fetchWithTimeout(`${url}/playlists/${idOrSlug}`);
                 if (response.ok) {
                     const playlist = await response.json();
                     return playlist;

package/dist/src/utilities/feral-file-artwork.js

@@ -10,6 +10,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveFeralFileArtwork = resolveFeralFileArtwork;
 exports.parseFeralFileArtworkId = parseFeralFileArtworkId;
+const http_1 = require("./http");
 const user_agent_1 = require("./user-agent");
 /**
  * resolveFeralFileArtwork resolves a public Feral File artwork id into indexer
@@ -19,7 +20,7 @@ const user_agent_1 = require("./user-agent");
  * @param fetchImpl - Fetch implementation, injected by tests.
  * @returns Token coordinates suitable for ff-indexer-v2 lookup.
  */
-async function resolveFeralFileArtwork(artworkId, fetchImpl = fetch) {
+async function resolveFeralFileArtwork(artworkId, fetchImpl = http_1.defaultDeadlineFetch) {
     const normalizedArtworkId = artworkId.trim();
     if (!normalizedArtworkId) {
         throw new Error('Feral File artwork id is required');

package/dist/src/utilities/ff-marketplace.js

@@ -50,6 +50,7 @@ exports.resolveFeralFileToken = resolveFeralFileToken;
  * Show URLs are rejected: a single exhibition spans multiple series, which
  * is wider than v1 supports.
  */
+const http_1 = require("./http");
 const logger = __importStar(require("../logger"));
 const feral_file_artwork_1 = require("./feral-file-artwork");
 const user_agent_1 = require("./user-agent");
@@ -57,7 +58,7 @@ const FF_API_BASE = 'https://feralfile.com/api';
 async function ffFetch(path) {
     const url = `${FF_API_BASE}${path}`;
     logger.debug(`[FF API] GET ${url}`);
-    const response = await fetch(url, {
+    const response = await (0, http_1.fetchWithTimeout)(url, {
         headers: { 'User-Agent': user_agent_1.USER_AGENT, Accept: 'application/json' },
     });
     if (!response.ok) {

package/dist/src/utilities/ff1-compatibility.js

@@ -38,6 +38,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveConfiguredDevice = resolveConfiguredDevice;
 exports.assertFF1CommandCompatibility = assertFF1CommandCompatibility;
+const http_1 = require("./http");
 const config_1 = require("../config");
 const device_lookup_1 = require("./device-lookup");
 const logger = __importStar(require("../logger"));
@@ -113,7 +114,9 @@ function resolveConfiguredDevice(deviceName, options = {}) {
  * const result = await assertFF1CommandCompatibility(device, 'displayPlaylist');
  */
 async function assertFF1CommandCompatibility(device, command, options = {}) {
-    const fetchFn = options.fetchFn || globalThis.fetch.bind(globalThis);
+    // Default probe fetch rides the shared deadline: a device that accepts
+    // the TCP connection but never answers must not hang `ff-cli ssh`.
+    const fetchFn = options.fetchFn || ((input, init) => (0, http_1.fetchWithTimeout)(input, init ?? {}));
     const policy = getCommandPolicy(command);
     const versionResult = await detectFF1VersionSafely(device.host, buildVersionHeaders(device), fetchFn);
     return resolveCompatibility(device, command, policy, versionResult);

package/dist/src/utilities/ff1-device.js

@@ -40,6 +40,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isTransientDeviceNetworkError = isTransientDeviceNetworkError;
 exports.parseRetryAfterMs = parseRetryAfterMs;
 exports.sendPlaylistToDevice = sendPlaylistToDevice;
+const http_1 = require("./http");
 const logger = __importStar(require("../logger"));
 const config_1 = require("../config");
 const ff1_compatibility_1 = require("./ff1-compatibility");
@@ -178,7 +179,9 @@ function parseRetryAfterMs(headerValue) {
  */
 async function sendPlaylistToDevice({ playlist, deviceName }, overrides = {}) {
     const dependencies = {
-        fetchFn: overrides.fetchFn ?? globalThis.fetch.bind(globalThis),
+        // Production default rides the shared deadline; injected test fetches
+        // are preserved untouched (#101 review).
+        fetchFn: overrides.fetchFn ?? http_1.defaultDeadlineFetch,
         getTopicIdFn: overrides.getTopicIdFn ?? topic_store_1.getTopicId,
         getRelayerConfigFn: overrides.getRelayerConfigFn ?? config_1.getFF1RelayerConfig,
         waitFn: overrides.waitFn ?? waitForRetry,

package/dist/src/utilities/ff1-relayer.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sendPlaylistViaRelayer = sendPlaylistViaRelayer;
+const http_1 = require("./http");
 function nestedOk(value) {
     if (!value || typeof value !== 'object') {
         return undefined;
@@ -26,7 +27,8 @@ function nestedOk(value) {
  * and JSON parsing errors.
  */
 async function sendPlaylistViaRelayer(input) {
-    const fetchFn = input.fetchFn ?? globalThis.fetch.bind(globalThis);
+    // Production default rides the shared deadline (#101 review).
+    const fetchFn = input.fetchFn ?? http_1.defaultDeadlineFetch;
     let url;
     try {
         url = new URL('/api/cast', input.baseUrl);

package/dist/src/utilities/fxhash-marketplace.js

@@ -51,6 +51,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveFxhashIteration = resolveFxhashIteration;
 exports.resolveFxhashProject = resolveFxhashProject;
+const http_1 = require("./http");
 const logger = __importStar(require("../logger"));
 const user_agent_1 = require("./user-agent");
 const FXHASH_GRAPHQL = 'https://api.fxhash.xyz/graphql';
@@ -63,7 +64,7 @@ const FXHASH_GRAPHQL = 'https://api.fxhash.xyz/graphql';
 async function resolveFxhashIteration(slug) {
     logger.debug(`[fxhash] Resolving iteration slug "${slug}"`);
     const query = 'query ($slug: String!) { objkt(slug: $slug) { gentkContractAddress onChainId } }';
-    const response = await fetch(FXHASH_GRAPHQL, {
+    const response = await (0, http_1.fetchWithTimeout)(FXHASH_GRAPHQL, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', 'User-Agent': user_agent_1.USER_AGENT },
         body: JSON.stringify({ query, variables: { slug } }),
@@ -115,7 +116,7 @@ async function resolveFxhashProject(slug) {
         '    }' +
         '  }' +
         '}';
-    const response = await fetch(FXHASH_GRAPHQL, {
+    const response = await (0, http_1.fetchWithTimeout)(FXHASH_GRAPHQL, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', 'User-Agent': user_agent_1.USER_AGENT },
         body: JSON.stringify({ query, variables: { slug } }),

package/dist/src/utilities/handoff-client.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TopicHandoffReceiver = void 0;
+const http_1 = require("./http");
 const handoff_crypto_1 = require("./handoff-crypto");
 const DEFAULT_HANDOFF_URL = 'https://handoff.feralfile.com';
 function brokerBaseUrl(value) {
@@ -69,7 +70,8 @@ class TopicHandoffReceiver {
     }
     /** Ask the handoff broker for a one-time six-digit pairing channel. */
     static async create(options = {}) {
-        const fetchFn = options.fetchFn ?? globalThis.fetch.bind(globalThis);
+        // Production default rides the shared deadline (#101 review).
+        const fetchFn = options.fetchFn ?? http_1.defaultDeadlineFetch;
         const baseUrl = brokerBaseUrl(options.baseUrl);
         const keyPair = await (0, handoff_crypto_1.generateHandoffKeyPair)();
         const publicKey = await (0, handoff_crypto_1.exportHandoffPublicJwk)(keyPair.publicKey);

package/dist/src/utilities/http.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Shared fetch-with-timeout for every outbound HTTP call in the CLI.
+ *
+ * Bare `fetch` has no deadline: a stalled connect or an unanswered request
+ * hangs the command silently — the failure mode agents can least diagnose,
+ * and the one behind #97. Every resolver and indexer call goes through here
+ * so "silent hang" is structurally impossible, not per-call-site discipline.
+ *
+ * Callers that pass their own `signal` keep it (composed with the deadline
+ * via AbortSignal.any), so cancellation semantics are never silently
+ * replaced by a timeout.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultDeadlineFetch = exports.DEFAULT_HTTP_TIMEOUT_MS = void 0;
+exports.fetchWithTimeout = fetchWithTimeout;
+exports.DEFAULT_HTTP_TIMEOUT_MS = 20_000;
+function fetchWithTimeout(input, init = {}, timeoutMs = exports.DEFAULT_HTTP_TIMEOUT_MS) {
+    const deadline = AbortSignal.timeout(timeoutMs);
+    const signals = [deadline];
+    if (init.signal) {
+        signals.push(init.signal);
+    }
+    else if (input instanceof Request && input.signal) {
+        // A Request input carries its own abort signal; passing only the
+        // deadline in init would silently REPLACE it (init wins over the
+        // request's signal in fetch), stripping the caller's cancellation.
+        signals.push(input.signal);
+    }
+    const signal = signals.length > 1 ? AbortSignal.any(signals) : deadline;
+    return fetch(input, { ...init, signal });
+}
+/**
+ * Drop-in `fetch` for production defaults of injectable-fetch modules:
+ * identical signature, deadline attached. Modules that accept a `fetchFn`
+ * override default to this instead of bare `globalThis.fetch`, so tests
+ * keep full injection control while production can never hang.
+ */
+const defaultDeadlineFetch = (input, init) => fetchWithTimeout(input, init ?? {});
+exports.defaultDeadlineFetch = defaultDeadlineFetch;

package/dist/src/utilities/neort-marketplace.js

@@ -58,6 +58,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveNeortArt = resolveNeortArt;
+const http_1 = require("./http");
 const logger = __importStar(require("../logger"));
 const user_agent_1 = require("./user-agent");
 const NEORT_API_BASE = 'https://api.neort.io/v1';
@@ -70,7 +71,7 @@ const NEORT_CDN_BASE = 'https://d32h66pp7fue57.cloudfront.net';
  */
 async function resolveNeortArt(id) {
     logger.debug(`[neort] Resolving art id "${id}"`);
-    const response = await fetch(`${NEORT_API_BASE}/art/${encodeURIComponent(id)}`, {
+    const response = await (0, http_1.fetchWithTimeout)(`${NEORT_API_BASE}/art/${encodeURIComponent(id)}`, {
         headers: { 'User-Agent': user_agent_1.USER_AGENT, Accept: 'application/json' },
     });
     if (!response.ok) {

package/dist/src/utilities/nft-indexer.js

@@ -4,6 +4,7 @@
  * to retrieve comprehensive token information.
  */
 const GRAPHQL_ENDPOINT = 'https://indexer.feralfile.com/graphql';
+const { fetchWithTimeout } = require('./http');
 const logger = require('../logger');
 const { applyItemTiming } = require('./playlist-builder');
 // Polling configuration (in milliseconds)
@@ -174,7 +175,7 @@ async function queryTokens(params = {}) {
         const headers = { 'Content-Type': 'application/json' };
         logger.debug('[NFT Indexer] Querying tokens:', { token_cids, owners, limit, offset });
         logger.debug('[NFT Indexer] GraphQL query:', query);
-        const response = await fetch(GRAPHQL_ENDPOINT, {
+        const response = await fetchWithTimeout(GRAPHQL_ENDPOINT, {
             method: 'POST',
             headers,
             body: JSON.stringify({ query }),
@@ -598,7 +599,7 @@ async function getNFTTokenInfoSingle(params, duration, options = {}) {
  * @param {number} duration - Display duration in seconds
  * @returns {Promise<Array>} Array of DP1 items
  */
-async function getNFTTokenInfoBatch(tokens, duration) {
+async function getNFTTokenInfoBatch(tokens, duration, onProgress) {
     logger.info(`[NFT Indexer] 📦 Starting batch processing for ${tokens.length} token(s)...`);
     logger.debug('[NFT Indexer] Batch tokens:', tokens);
     const results = [];
@@ -620,6 +621,19 @@ async function getNFTTokenInfoBatch(tokens, duration) {
         const failed = batchResults.filter((r) => !r.success).length;
         logger.info(`[NFT Indexer] Batch complete: ${successful} success, ${failed} failed`);
         results.push(...batchResults);
+        // Indexing previously-unseen tokens can take minutes (the indexer warms
+        // renditions by polling); without user-visible progress the CLI reads as
+        // hung. logger.info above is verbose-gated, so callers that face a human
+        // pass onProgress to render it. Errors in the callback must never break
+        // the batch — reporting is strictly best-effort.
+        if (typeof onProgress === 'function') {
+            try {
+                onProgress(results.length, tokens.length);
+            }
+            catch {
+                /* progress display is best-effort */
+            }
+        }
     }
     logger.info(`[NFT Indexer] ✓ Batch processing complete: ${results.length} total results`);
     const successCount = results.filter((r) => r.success && r.item).length;
@@ -687,7 +701,7 @@ async function triggerIndexingAsync(chain, contractAddress, tokenId) {
             token_cids: [tokenCID],
         };
         const headers = { 'Content-Type': 'application/json' };
-        const response = await fetch(GRAPHQL_ENDPOINT, {
+        const response = await fetchWithTimeout(GRAPHQL_ENDPOINT, {
             method: 'POST',
             headers,
             body: JSON.stringify({ query: mutation, variables }),
@@ -742,7 +756,7 @@ async function queryJobStatus(jobId) {
         const query = JOB_STATUS_QUERY;
         const variables = { job_id: id };
         const headers = { 'Content-Type': 'application/json' };
-        const response = await fetch(GRAPHQL_ENDPOINT, {
+        const response = await fetchWithTimeout(GRAPHQL_ENDPOINT, {
             method: 'POST',
             headers,
             body: JSON.stringify({ query, variables }),

package/dist/src/utilities/objkt-marketplace.js

@@ -45,6 +45,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveObjktAlias = resolveObjktAlias;
+const http_1 = require("./http");
 const logger = __importStar(require("../logger"));
 const user_agent_1 = require("./user-agent");
 const OBJKT_GRAPHQL = 'https://data.objkt.com/v3/graphql';
@@ -56,7 +57,7 @@ const OBJKT_GRAPHQL = 'https://data.objkt.com/v3/graphql';
 async function resolveObjktAlias(alias) {
     logger.debug(`[Objkt] Resolving alias "${alias}"`);
     const query = 'query ($path: String!) { fa(where: { path: { _eq: $path } }) { contract } }';
-    const response = await fetch(OBJKT_GRAPHQL, {
+    const response = await (0, http_1.fetchWithTimeout)(OBJKT_GRAPHQL, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', 'User-Agent': user_agent_1.USER_AGENT },
         body: JSON.stringify({ query, variables: { path: alias } }),

package/dist/src/utilities/opensea-marketplace.js

@@ -59,6 +59,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveOpenSeaCollection = resolveOpenSeaCollection;
+const http_1 = require("./http");
 const logger = __importStar(require("../logger"));
 const user_agent_1 = require("./user-agent");
 /**
@@ -80,7 +81,7 @@ const FALLBACK_HINT = 'Paste a specific token URL (opensea.io/item/ethereum/{con
  */
 async function resolveOpenSeaCollection(slug) {
     logger.debug(`[OpenSea] Resolving collection slug "${slug}"`);
-    const response = await fetch(`https://opensea.io/collection/${encodeURIComponent(slug)}`, {
+    const response = await (0, http_1.fetchWithTimeout)(`https://opensea.io/collection/${encodeURIComponent(slug)}`, {
         headers: { 'User-Agent': user_agent_1.USER_AGENT, Accept: 'text/html' },
     });
     if (!response.ok) {

package/dist/src/utilities/playlist-source.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isPlaylistSourceUrl = isPlaylistSourceUrl;
 exports.loadPlaylistSource = loadPlaylistSource;
 exports.resolvePlaySource = resolvePlaySource;
+const http_1 = require("./http");
 const fs_1 = require("fs");
 // playlist-builder is still CommonJS; require keeps the interop simple.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -39,7 +40,7 @@ async function loadPlaylistSource(source) {
         throw new Error('Playlist source is required');
     }
     if (isPlaylistSourceUrl(trimmedSource)) {
-        const response = await fetch(trimmedSource);
+        const response = await (0, http_1.fetchWithTimeout)(trimmedSource);
         if (!response.ok) {
             throw new Error(`Failed to fetch playlist URL: ${response.status} ${response.statusText}`);
         }

package/dist/src/utilities/raster-client.js

@@ -57,6 +57,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RasterUnreachableError = void 0;
 exports.resolveTokenToArtwork = resolveTokenToArtwork;
 exports.resolveSlugToArtwork = resolveSlugToArtwork;
 exports.resolveAddressToArtist = resolveAddressToArtist;
@@ -66,6 +67,14 @@ exports.formatSummaryLine = formatSummaryLine;
 const logger = __importStar(require("../logger"));
 const user_agent_1 = require("./user-agent");
 const DEFAULT_RASTER_GRAPHQL_URL = 'https://api.raster.art/graphql';
+/**
+ * Hard ceiling on a single Raster round trip. Without it, a stalled TCP
+ * connect or unanswered request leaves `find` hanging with no output (#97) —
+ * the failure mode agents can least diagnose. 20 s is generous for a
+ * transcontinental GraphQL query and still turns "silent hang" into a fast,
+ * actionable error.
+ */
+const RASTER_REQUEST_TIMEOUT_MS = 20_000;
 // CAIP-2 chain IDs for the chains the FF indexer supports.
 // Tezos mainnet's CAIP form uses the genesis block hash (NetXdQprcVkpaWU),
 // not the human-readable "tezos:mainnet" — Raster returns the hash form on
@@ -78,6 +87,19 @@ const INDEXER_CHAIN_TO_CAIP = {
     ethereum: 'eip155:1',
     tezos: 'tezos:NetXdQprcVkpaWU',
 };
+/**
+ * Raster could not be reached at the network level (connect failure, broken
+ * IPv6 path, timeout). Distinct from API-level errors so callers that hold
+ * usable token coordinates can degrade gracefully instead of dying — Raster
+ * only enriches a find, it is not required to build a playable playlist.
+ */
+class RasterUnreachableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RasterUnreachableError';
+    }
+}
+exports.RasterUnreachableError = RasterUnreachableError;
 function caipToIndexerChain(caip) {
     return CAIP_TO_INDEXER_CHAIN[caip] ?? null;
 }
@@ -99,16 +121,46 @@ async function rasterQuery(query, variables) {
     if (apiKey) {
         headers['x-api-key'] = apiKey;
     }
-    const response = await fetch(endpoint, {
-        method: 'POST',
-        headers,
-        body: JSON.stringify({ query, variables }),
-    });
+    let response;
+    try {
+        response = await fetch(endpoint, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ query, variables }),
+            signal: AbortSignal.timeout(RASTER_REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        // Undici's "fetch failed" carries no endpoint and no cause in its
+        // message — name the host and the real failure so the error is
+        // actionable, and let callers detect network failure by type.
+        const cause = error.cause;
+        const detail = cause?.message ?? error.message;
+        throw new RasterUnreachableError(`Raster API unreachable (${endpoint}): ${detail}`);
+    }
     if (!response.ok) {
-        const body = await response.text();
+        // Body text is best-effort context; the HTTP status alone is the error.
+        // A body read that rejects here must not mask the status — and an HTTP
+        // error is an API-level failure, deliberately NOT RasterUnreachableError.
+        const body = await response.text().catch(() => '');
         throw new Error(`Raster API ${response.status} ${response.statusText}: ${body.slice(0, 200)}`);
     }
-    const payload = (await response.json());
+    // The network-error boundary extends through body consumption: a response
+    // whose stream stalls past the headers or terminates mid-body rejects
+    // HERE, not in fetch() above. Those must still surface as
+    // RasterUnreachableError or resolveCoords cannot perform its promised
+    // single-token fallback. (A 200 whose body cannot be read or parsed is
+    // unusable either way — falling back is right even for server-side
+    // garbage.)
+    let payload;
+    try {
+        payload = (await response.json());
+    }
+    catch (error) {
+        const cause = error.cause;
+        const detail = cause?.message ?? error.message;
+        throw new RasterUnreachableError(`Raster API unreachable (${endpoint}): response body failed: ${detail}`);
+    }
     if (payload.errors && payload.errors.length > 0) {
         throw new Error(`Raster API error: ${payload.errors.map((e) => e.message).join('; ')}`);
     }

package/dist/src/utilities/ssh-access.js

@@ -37,6 +37,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sendSshAccessCommand = sendSshAccessCommand;
+const http_1 = require("./http");
 const logger = __importStar(require("../logger"));
 const ff1_compatibility_1 = require("./ff1-compatibility");
 /**
@@ -106,7 +107,7 @@ async function sendSshAccessCommand({ enabled, deviceName, publicKey, ttlSeconds
         if (device.apiKey) {
             headers['API-KEY'] = device.apiKey;
         }
-        const response = await fetch(apiUrl, {
+        const response = await (0, http_1.fetchWithTimeout)(apiUrl, {
             method: 'POST',
             headers,
             body: JSON.stringify(requestBody),

package/dist/src/utilities/verse-marketplace.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveVerseSeries = resolveVerseSeries;
+const http_1 = require("./http");
 /**
  * Resolve a Verse series slug to representative Ethereum token coordinates.
  *
@@ -15,7 +16,7 @@ exports.resolveVerseSeries = resolveVerseSeries;
  */
 async function resolveVerseSeries(slug) {
     const url = `https://verse.works/series/${encodeURIComponent(slug)}`;
-    const response = await fetch(url);
+    const response = await (0, http_1.fetchWithTimeout)(url);
     if (!response.ok) {
         throw new Error(`Verse series lookup failed for ${slug}: ${response.status}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feralfile/cli",
-  "version": "2.2.1",
+  "version": "2.2.2",
   "description": "CLI for building, signing, and playing DP-1 playlists of digital art on Feral File devices",
   "repository": {
     "type": "git",