@feralfile/cli 2.10.1 → 4.0.0

package/dist/src/commands/find.js

@@ -4,7 +4,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findCommand = void 0;
-exports.buildRasterMediaItems = buildRasterMediaItems;
 exports.parseLimitOption = parseLimitOption;
 exports.decideActions = decideActions;
 const commander_1 = require("commander");
@@ -22,9 +21,10 @@ const neort_marketplace_1 = require("../utilities/neort-marketplace");
 const verse_marketplace_1 = require("../utilities/verse-marketplace");
 const raster_client_1 = require("../utilities/raster-client");
 const playlist_cast_1 = require("../utilities/playlist-cast");
-// nft-indexer + playlist-builder are still CommonJS; require keeps interop simple.
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const { getNFTTokenInfoBatch } = require('../utilities/nft-indexer');
+const token_source_1 = require("../utilities/token-source");
+const token_source_raster_1 = require("../utilities/token-source-raster");
+const config_1 = require("../config");
+// playlist-builder is still CommonJS; require keeps interop simple.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { buildDP1Playlist, buildUrlItem } = require('../utilities/playlist-builder');
 /**
@@ -35,18 +35,56 @@ const { buildDP1Playlist, buildUrlItem } = require('../utilities/playlist-builde
  */
 const DP1_MAX_ITEMS = 1024;
 const RASTER_PAGE_SIZE = 100;
+/**
+ * FIND_NON_INTERACTIVE_HINT is what `find` tells a caller without a terminal
+ * when one of its questions comes up. `-y` answers every question with its
+ * default, and that default is to display, so the hint names `--no-display` in
+ * the same breath for a caller that only wants the file.
+ */
+const FIND_NON_INTERACTIVE_HINT = 'Re-run with -y to accept the defaults (it builds the playlist and displays it on your FF1); add --no-display to only save it.';
+/**
+ * playAPageHint points a caller who handed `find` a page it cannot resolve to
+ * the command that shows a page as it is.
+ *
+ * @param {string} input - The URL the caller gave `find`
+ * @returns {string} One line naming `ff-cli display --web`
+ */
+function playAPageHint(input) {
+    return `To show this page itself on your FF1, run: ff-cli display --web "${input}"`;
+}
+/**
+ * displayIntent folds the hidden `--play` / `--no-play` spellings into
+ * `--display` / `--no-display`.
+ *
+ * The verb for art is display, not play (B&F weekly 2026-11-03; Canon
+ * reference/naming-brand.md §3.4), so `find` takes `--display` and
+ * `--no-display`. `-p, --play` and `--no-play` stay accepted, hidden from
+ * help, so existing scripts and agents keep working. Commander stores the two
+ * spellings under separate keys (`display`, `play`); this is the one place
+ * that reads both. The current spelling wins when a caller passes both.
+ *
+ * @param {FindOptions} options - Parsed `find` options
+ * @returns {boolean | undefined} true to display, false to never cast,
+ *   undefined when neither spelling was passed
+ */
+function displayIntent(options) {
+    return options.display ?? options.play;
+}
 exports.findCommand = new commander_1.Command('find')
     .description('Find an artwork on the web and build a DP-1 playlist')
-    .argument('<input>', 'URL (Objkt / fxhash / Art Blocks / OpenSea / SuperRare / Feral File / Neort / Verse / Raster), `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, or a wallet address')
+    .argument('<input>', 'URL (Objkt / fxhash / Art Blocks / OpenSea / SuperRare / Feral File / Neort / Verse / Raster), `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, or a wallet address (picks one work by the artist at that address; for what a wallet owns, see `ff-cli build --help`)')
     .option('-o, --output <path>', 'Save the playlist to this file (default: ./<slug>.json)')
     .option('-l, --limit <n>', 'Max tokens to include from the series (default: all)')
-    .option('-p, --play', 'Play the playlist on an FF1 device after building')
-    .option('--no-play', 'Never cast to a device; combine with -y to build and save without playing')
-    .option('-d, --device <name>', 'Device to play on (used with --play; default: first configured)')
+    .option('--display', 'Display the playlist on an FF1 device after building')
+    .option('--no-display', 'Never cast to a device; combine with -y to build and save without displaying')
+    // The retired spellings of the two flags above, accepted but never listed; see displayIntent.
+    .addOption(new commander_1.Option('-p, --play').hideHelp())
+    .addOption(new commander_1.Option('--no-play').hideHelp())
+    .option('-d, --device <name>', 'Device to display on (used with --display; default: first configured)')
     .option('--publish', 'Publish the playlist to a configured feed server')
     .option('-s, --server <index>', 'Feed server index (used with --publish)')
-    .option('-y, --yes', 'Skip interactive prompts. Without --output or --publish, -y plays the playlist on a device; add --no-play to skip casting')
-    .option('--skip-verify', 'Skip signature verification before --play (mirrors `ff-cli play --skip-verify`)')
+    .option('-y, --yes', 'Skip interactive prompts. Without --output or --publish, -y displays the playlist on a device; add --no-display to skip casting')
+    .option('--skip-verify', 'Skip signature verification before --display (mirrors `ff-cli display --skip-verify`)')
     .action(async (input, options) => {
     try {
         console.log(chalk_1.default.blue('\nFind on Feral File CLI\n'));
@@ -56,6 +94,11 @@ exports.findCommand = new commander_1.Command('find')
             console.error(chalk_1.default.dim('Supported URLs: Objkt, fxhash, Art Blocks, OpenSea, SuperRare, Feral File, Neort, Verse, Raster. ' +
                 'Or: `ethereum:{contract}:{tokenId}`, `tezos:{contract}:{tokenId}`, ' +
                 'or a wallet address (`0x...` / `tz1.../tz2.../tz3...`).'));
+            // A plain web page or media URL is not an artwork lookup at all; `display`
+            // casts those directly, so name it rather than leave the caller stuck.
+            if (/^https?:\/\//i.test(input.trim())) {
+                console.error(chalk_1.default.dim(`To display a web page or media URL as it is, run: ff-cli display "${input}"`));
+            }
             process.exit(1);
         }
         if (parsed.kind === 'unsupported') {
@@ -65,9 +108,12 @@ exports.findCommand = new commander_1.Command('find')
                 return;
             }
             console.error(chalk_1.default.red(parsed.reason));
+            // `display` sends unrecognized pages on these hosts here, so the way out
+            // of that loop has to be printed on this side too.
+            console.error(chalk_1.default.dim(playAPageHint(input)));
             process.exit(1);
         }
-        // Neort is off-chain; its items skip Raster + FF indexer entirely and
+        // Neort is off-chain; its items skip the token source entirely and
         // build a DP-1 entry directly from Neort's API response.
         if (parsed.kind === 'neort-art') {
             await runNeortFind(parsed.id, options);
@@ -113,14 +159,13 @@ async function runResolvedTarget(target, options) {
     else if (target.kind === 'token-list') {
         const allTokens = target.coords.map((coords) => ({
             ...coords,
-            mediaUrl: null,
-            mediaType: null,
+            rasterToken: null,
         }));
         tokens = allTokens.slice(0, limit);
         seriesHasMore = allTokens.length > limit || !!target.hasMore;
     }
     else {
-        tokens = [{ ...target.coords, mediaUrl: null, mediaType: null }];
+        tokens = [{ ...target.coords, rasterToken: null }];
     }
     if (tokens.length === 0) {
         console.error(chalk_1.default.red('Series has no tokens on supported chains (Ethereum + Tezos mainnet).'));
@@ -136,48 +181,21 @@ async function runResolvedTarget(target, options) {
         console.log(chalk_1.default.dim('Cancelled.'));
         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) {
+    const source = (0, token_source_1.getTokenSource)();
+    const label = source.name === 'raster' ? 'Raster' : 'FF indexer';
+    console.log(chalk_1.default.dim(`Resolving ${tokens.length} token${tokens.length === 1 ? '' : 's'} via ${label}...`));
+    // The indexer warms previously-unseen tokens by polling, which
+    // takes minutes on a large series; Raster answers from its own index.
+    if (source.name === 'indexer' && 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
-    // their natural length (DP-1 §4.1); static items get the config default.
-    let items = await getNFTTokenInfoBatch(tokens.map((t) => ({
-        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
-    // that (off-chain provenance, same shape as the Neort path), so the
-    // series still builds into a signable, verifiable playlist instead of
-    // failing the way it did before. The indexer is tried first so tokens
-    // it *can* resolve keep their richer on-chain provenance.
-    if (!Array.isArray(items) || items.length === 0) {
-        const rasterItems = buildRasterMediaItems(tokens, target);
-        if (rasterItems.length > 0) {
-            console.log(chalk_1.default.dim(`  FF indexer returned nothing; building ${rasterItems.length} item${rasterItems.length === 1 ? '' : 's'} directly from Raster media.`));
-            items = rasterItems;
+    const results = await resolveBuildTokens(source, tokens);
+    const items = (0, token_source_1.itemsOf)(results);
+    if (items.length === 0) {
+        console.error(chalk_1.default.red(`No tokens could be resolved via ${label}; cannot build playlist.`));
+        for (const message of (0, token_source_1.failureMessages)(results)) {
+            console.error(chalk_1.default.dim(`  ${message}`));
         }
-    }
-    if (!Array.isArray(items) || items.length === 0) {
-        console.error(chalk_1.default.red('No tokens could be indexed; cannot build playlist.'));
-        console.error(chalk_1.default.dim('  The FF indexer may be under load when warming a series of previously-unseen tokens.'));
-        console.error(chalk_1.default.dim('  Try `--limit 5` first to warm the cache, then re-run without --limit.'));
         process.exit(1);
     }
     const title = playlistTitleFor(target, items);
@@ -188,7 +206,10 @@ async function runResolvedTarget(target, options) {
     console.log(chalk_1.default.dim(`  ${items.length} item${items.length === 1 ? '' : 's'}`));
     const dropped = tokens.length - items.length;
     if (dropped > 0) {
-        console.log(chalk_1.default.dim(`  ${dropped} token${dropped === 1 ? '' : 's'} dropped during indexing`));
+        console.log(chalk_1.default.dim(`  ${dropped} token${dropped === 1 ? '' : 's'} could not be resolved:`));
+        for (const message of (0, token_source_1.failureMessages)(results)) {
+            console.log(chalk_1.default.dim(`    ${message}`));
+        }
     }
     console.log();
     const actions = await decideActions(options);
@@ -279,6 +300,11 @@ async function resolveTarget(input, parsed, skipPrompt, limitOption) {
         if (catalog.length === 0) {
             throw new Error('Artist has no artworks indexed on Raster.');
         }
+        // A wallet address reads naturally as "what this wallet owns", and this
+        // path builds something else: one work by the artist at the address. Say
+        // so every time, so neither a person nor an agent mistakes the result.
+        console.log(chalk_1.default.dim('find on an address displays one work by the artist at that address. ' +
+            'For what the wallet owns, use build with a query_address requirement (ff-cli build --help).'));
         const picked = await pickFromCatalog(catalog, skipPrompt);
         return {
             kind: 'series',
@@ -318,11 +344,11 @@ 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.
+ * fall back to single-token mode so we still build something to display.
  *
  * 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
+ * build a single-token playlist to display, and a network blip on one optional
  * dependency must not kill the whole command (#97).
  */
 async function resolveCoords(coords) {
@@ -345,7 +371,7 @@ async function resolveCoords(coords) {
 }
 /**
  * Build the playlist title. For series, "Artist — Series Title". For a
- * one-item fallback, use the indexer's token name (already in the item)
+ * one-item fallback, use the token source's name (already in the item)
  * with a fall-through to coords if name is missing.
  */
 function playlistTitleFor(target, items) {
@@ -359,30 +385,30 @@ function playlistTitleFor(target, items) {
     return items[0]?.title ?? `Token ${target.coords.tokenId}`;
 }
 /**
- * Build DP-1 items directly from Raster's per-token media, bypassing the FF
- * indexer. Used as a fallback when the indexer resolves nothing — tokens
- * without a Raster `mediaUrl` are dropped (nothing playable to point at).
+ * resolveBuildTokens turns the tokens to build into results, one per token.
  *
- * Item shape matches the Neort off-chain path (`buildUrlItem` →
- * `provenance.offChainURI`), so the resulting playlist signs and verifies
- * normally. Titles are "<Series> #<tokenId>" for series, falling back to the
- * series/coords title for a single token.
+ * When every token already carries its Raster row (a Raster series page) and
+ * Raster is the token source, the rows are mapped directly: the page already
+ * paid for every field, so asking again would double the requests. Any other
+ * mix goes through the token source by coordinate.
  */
-function buildRasterMediaItems(tokens, target) {
-    const seriesTitle = target.kind === 'series' ? target.summary.title : undefined;
-    const items = [];
-    for (const t of tokens) {
-        if (!t.mediaUrl) {
-            continue;
-        }
-        const title = seriesTitle ? `${seriesTitle} #${t.tokenId}` : `Token ${t.tokenId}`;
-        // No explicit duration: auto timing (video/audio play their natural
-        // length). `mediaType` carries Raster's type so an extensionless IPFS
-        // contentUrl is still classified correctly — otherwise a video would be
-        // stamped a fixed duration and play as a still.
-        items.push(buildUrlItem(t.mediaUrl, undefined, { title, mimeType: t.mediaType ?? undefined }));
-    }
-    return items;
+async function resolveBuildTokens(source, tokens) {
+    const rows = tokens.map((t) => t.rasterToken);
+    if (source.name === 'raster' && rows.every((row) => row !== null)) {
+        const entries = tokens.map((t, i) => ({ token: rows[i], requested: coordinateOf(t) }));
+        return (0, token_source_raster_1.itemsFromRasterTokens)(entries, (0, config_1.getTokenSourceConfig)().ipfsGateways);
+    }
+    // Unconditional progress: the final N/N line IS the "resolution finished"
+    // signal, including for a single-batch run.
+    return source.resolveTokens(tokens.map(coordinateOf), {
+        onProgress: (done, total) => {
+            console.log(chalk_1.default.dim(`  ${done}/${total} tokens resolved...`));
+        },
+    });
+}
+/** coordinateOf converts a find token to the token source's coordinate shape. */
+function coordinateOf(token) {
+    return { chain: token.chain, contractAddress: token.contract, tokenId: token.tokenId };
 }
 function parseLimitOption(limitStr) {
     if (limitStr === undefined) {
@@ -425,8 +451,7 @@ async function fetchTokens(summary, limit) {
                 chain: t.chain,
                 contract: t.contractAddress,
                 tokenId: t.tokenId,
-                mediaUrl: t.mediaUrl,
-                mediaType: t.mediaType,
+                rasterToken: t.token,
             });
         }
         if (hasMore || page.nextCursor === null) {
@@ -439,7 +464,7 @@ async function fetchTokens(summary, limit) {
         cursor = page.nextCursor;
     }
     if (skipped > 0) {
-        console.log(chalk_1.default.yellow(`  Skipped ${skipped} token${skipped === 1 ? '' : 's'} on unsupported chains (FF indexer covers eth + tezos mainnet only).`));
+        console.log(chalk_1.default.yellow(`  Skipped ${skipped} token${skipped === 1 ? '' : 's'} on unsupported chains (ff-cli builds Ethereum and Tezos mainnet only).`));
     }
     return { tokens: collected, hasMore };
 }
@@ -452,7 +477,7 @@ async function pickFromCatalog(catalog, skipPrompt) {
         console.log(chalk_1.default.dim(`  ${i}: ${row.title}`));
     });
     console.log();
-    const prompt = (0, prompt_1.createPrompt)();
+    const prompt = (0, prompt_1.createPrompt)(FIND_NON_INTERACTIVE_HINT);
     const answer = await prompt.ask(`Pick one (0-${catalog.length - 1}, default 0): `);
     prompt.close();
     console.log();
@@ -467,7 +492,7 @@ async function pickFromCatalog(catalog, skipPrompt) {
 async function confirmMakePlaylist(count, hasMore) {
     const noun = count === 1 ? 'token' : 'tokens';
     const label = hasMore ? `the first ${count} ${noun}` : `${count} ${noun}`;
-    const prompt = (0, prompt_1.createPrompt)();
+    const prompt = (0, prompt_1.createPrompt)(FIND_NON_INTERACTIVE_HINT);
     const yes = await (0, prompt_1.promptYesNo)(prompt.ask, `Build playlist with ${label}?`, true);
     prompt.close();
     console.log();
@@ -476,20 +501,23 @@ async function confirmMakePlaylist(count, hasMore) {
 /**
  * Decide which post-build actions to run.
  *
- * Precedence: explicit flags (--play / --publish) win and may combine. If no
- * flag is set, fall back to --yes default (Play) or an interactive 3-way
- * prompt. Save is unconditional and already done before this is called.
+ * Precedence: explicit flags (--display / --publish) win and may combine. If
+ * no flag is set, fall back to the --yes default (display) or an interactive
+ * 3-way prompt. Save is unconditional and already done before this is called.
  *
- * `--no-play` (commander sets `play === false`) is an opt-out that removes
- * casting from every path, including the `--yes` default and the interactive
- * prompt. It is additive: `--yes` alone keeps its deliberate "max-satisfaction
- * default for scripted use" of Play, and this must not change that. Because
- * `--no-play` already states the user's intent, it never opens the prompt.
+ * `--no-display` (commander sets `display === false`) is an opt-out that
+ * removes casting from every path, including the `--yes` default and the
+ * interactive prompt. It is additive: `--yes` alone keeps its deliberate
+ * "max-satisfaction default for scripted use" of displaying, and this must not
+ * change that. Because `--no-display` already states the user's intent, it
+ * never opens the prompt. The hidden `--play` / `--no-play` spellings mean the
+ * same (displayIntent). The internal action keeps its name, 'play'.
  */
 async function decideActions(options) {
     const flagActions = [];
-    const noPlay = options.play === false;
-    if (options.play) {
+    const display = displayIntent(options);
+    const noDisplay = display === false;
+    if (display) {
         flagActions.push('play');
     }
     if (options.publish) {
@@ -499,24 +527,34 @@ async function decideActions(options) {
         return flagActions;
     }
     // --output alone (with or without --yes) means "save mode" — the save was the action.
-    // --no-play likewise means the save was the action; never prompt or default to Play.
-    if (options.output || noPlay) {
+    // --no-display likewise means the save was the action; never prompt or default to display.
+    if (options.output || noDisplay) {
         return [];
     }
-    // --yes without --output defaults to Play (max-satisfaction default for scripted use).
+    // --yes without --output defaults to display (max-satisfaction default for scripted use).
     if (options.yes) {
         return ['play'];
     }
     return [await promptNextAction()];
 }
+/**
+ * promptNextAction asks what to do with a saved playlist when no flag said so.
+ *
+ * `p` and `play` stay accepted after the rename to display: a script that
+ * pipes its answer in must keep getting the same action.
+ *
+ * @returns {Promise<PostBuildAction>} The chosen action
+ * @throws {Error} On an answer that names no action
+ */
 async function promptNextAction() {
-    const prompt = (0, prompt_1.createPrompt)();
-    const answer = (await prompt.ask('Next? [P]lay on FF1 / just [S]ave / pub[L]ish to feed (default: Play): '))
+    const prompt = (0, prompt_1.createPrompt)('The playlist is saved. Pass --display to cast it, or --publish to publish it.');
+    const answer = (await prompt.ask('Next? [D]isplay on FF1 / just [S]ave / pub[L]ish to feed (default: Display): '))
         .trim()
         .toLowerCase();
     prompt.close();
     console.log();
-    if (!answer || answer === 'p' || answer === 'play' || answer === 'y' || answer === 'yes') {
+    const displayAnswers = ['', 'd', 'display', 'p', 'play', 'y', 'yes'];
+    if (displayAnswers.includes(answer)) {
         return 'play';
     }
     if (answer === 's' || answer === 'save' || answer === 'n' || answer === 'no') {
@@ -525,10 +563,10 @@ async function promptNextAction() {
     if (answer === 'l' || answer === 'pub' || answer === 'publish') {
         return 'publish';
     }
-    throw new Error(`Unrecognized choice: "${answer}". Use P, S, or L.`);
+    throw new Error(`Unrecognized choice: "${answer}". Use D, S, or L.`);
 }
 async function doPlay(playlist, deviceName, skipVerify) {
-    // Same verify → send gate `ff-cli play` uses, via the shared castPlaylist
+    // Same verify → send gate `ff-cli display` uses, via the shared castPlaylist
     // helper. `find`'s playlists are already signed by buildDP1Playlist (when a
     // key is configured), so no signing is requested here — an unsigned one
     // fails the verify gate with an actionable message instead of reaching the
@@ -549,7 +587,7 @@ async function doPlay(playlist, deviceName, skipVerify) {
                 'or pass --skip-verify to bypass.'));
         }
         else {
-            console.error(chalk_1.default.red('Play failed:'), result.error);
+            console.error(chalk_1.default.red('Display failed:'), result.error);
             if (result.deviceDetails) {
                 console.error(chalk_1.default.dim(`  Details: ${result.deviceDetails}`));
             }
@@ -560,8 +598,8 @@ async function doPlay(playlist, deviceName, skipVerify) {
     if (result.verified) {
         console.log(chalk_1.default.green('✓ Verified\n'));
     }
-    console.log(chalk_1.default.blue('Play on FF1'));
-    console.log(chalk_1.default.green('✓ Playing'));
+    console.log(chalk_1.default.blue('Display on FF1'));
+    console.log(chalk_1.default.green('✓ Displaying'));
     if (result.deviceName) {
         console.log(chalk_1.default.dim(`  Device: ${result.deviceName}`));
     }
@@ -610,7 +648,7 @@ async function doPublish(savedPath, serverArg, nonInteractive) {
 }
 /**
  * Neort flow. Off-chain platform with no on-chain coords, so we bypass
- * Raster + FF indexer and construct a single-item DP-1 playlist directly
+ * the token source and construct a single-item DP-1 playlist directly
  * from Neort's API response using the off-chain `provenance.offChainURI`
  * shape produced by `buildUrlItem`.
  */