@feralfile/cli 2.10.1 → 4.0.0

package/dist/src/commands/helpers/hidden-alias-help.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hiddenAliasHelp = void 0;
+const commander_1 = require("commander");
+/**
+ * dropAlias removes `cmd`'s first alias from a help term commander built, turning `display|play` back
+ * into `display`.
+ *
+ * Commander adds the alias as `name|alias` in exactly these two terms and nowhere else, so replacing
+ * that one token is enough; rebuilding the terms from scratch would copy commander internals that
+ * are not exported (humanReadableArgName).
+ *
+ * @param {string} term - The term commander built
+ * @param {Command} cmd - The command it describes
+ * @returns {string} The term without the alias
+ */
+function dropAlias(term, cmd) {
+    const alias = cmd.alias();
+    return alias ? term.replace(`${cmd.name()}|${alias}`, cmd.name()) : term;
+}
+/**
+ * hiddenAliasHelp is a commander help configuration that names a command by its name only, never
+ * by its alias.
+ *
+ * An alias in ff-cli is a retired command name kept so existing scripts and agents keep working:
+ * `play` became `display` (B&F weekly 2026-11-03; Canon reference/naming-brand.md §3.4). Commander
+ * would print it in the command list and the usage line (`display|play`), and help is where people
+ * and agents learn the CLI's words, so printing it would teach the retired verb again. The alias
+ * still parses and `ff-cli help play` still works; only the printed help drops it.
+ *
+ * Apply it to the program (the command list uses subcommandTerm) and to every aliased command (its
+ * own usage line uses commandUsage): `addCommand` does not copy help configuration to subcommands.
+ */
+exports.hiddenAliasHelp = {
+    subcommandTerm: (cmd) => dropAlias(new commander_1.Help().subcommandTerm(cmd), cmd),
+    commandUsage: (cmd) => dropAlias(new commander_1.Help().commandUsage(cmd), cmd),
+};

package/dist/src/commands/helpers/playlist-display.js

@@ -3,7 +3,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.displayPlaylistSummary = displayPlaylistSummary;
 exports.printPlaylistSourceLoadFailure = printPlaylistSourceLoadFailure;
 exports.printPlaylistVerificationFailure = printPlaylistVerificationFailure;
 exports.validatePlaylistSource = validatePlaylistSource;
@@ -11,18 +10,6 @@ exports.runValidateCommand = runValidateCommand;
 exports.runVerifyCommand = runVerifyCommand;
 const chalk_1 = __importDefault(require("chalk"));
 const playlist_source_1 = require("../../utilities/playlist-source");
-/**
- * Print the standard "playlist saved" footer with the next-step hint.
- *
- * Used by `chat` and `build` after they write a playlist to disk, so the
- * surface message stays consistent across both commands.
- */
-function displayPlaylistSummary(playlist, outputPath) {
-    console.log(chalk_1.default.green('\nPlaylist saved'));
-    console.log(chalk_1.default.dim(`  Output: ./${outputPath}`));
-    console.log(chalk_1.default.dim('  Next: play last | publish playlist'));
-    console.log();
-}
 /**
  * Print a focused failure for playlist source loading problems with a
  * URL-vs-file aware hint block.
@@ -45,7 +32,7 @@ function printPlaylistSourceLoadFailure(source, error) {
 }
 /**
  * Print playlist validation failure details consistently for commands that
- * validate structure before sending (for example `play`).
+ * validate structure before sending (for example `display`).
  */
 function printPlaylistVerificationFailure(verifyResult, source) {
     console.error(chalk_1.default.red(`\nPlaylist validation failed:${source ? ` (${source})` : ''}`), verifyResult.error);
@@ -55,7 +42,7 @@ function printPlaylistVerificationFailure(verifyResult, source) {
             console.log(chalk_1.default.yellow(`     • ${detail.path}: ${detail.message}`));
         });
     }
-    console.log(chalk_1.default.yellow('\n   Use --skip-verify to play anyway (not recommended)\n'));
+    console.log(chalk_1.default.yellow('\n   Use --skip-verify to display anyway (not recommended)\n'));
 }
 /**
  * Load a playlist from a path or URL and run parse-only validation (`validatePlaylist`).

package/dist/src/commands/helpers/prompt.js

@@ -36,23 +36,98 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.NonInteractiveError = exports.NON_TTY_ANSWER_TIMEOUT_MS = void 0;
+exports.isNonInteractiveError = isNonInteractiveError;
 exports.createPrompt = createPrompt;
 exports.promptYesNo = promptYesNo;
 const readline = __importStar(require("readline"));
 const chalk_1 = __importDefault(require("chalk"));
-function createPrompt() {
-    const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
-    const ask = async (question) => new Promise((resolve) => {
-        rl.question(chalk_1.default.yellow(question), (answer) => {
-            resolve(answer.trim());
+/**
+ * NON_TTY_ANSWER_TIMEOUT_MS bounds how long a question waits for an answer on
+ * a stdin that is not a terminal.
+ *
+ * Piped answers (`echo n | ff-cli find …`) arrive at once and still work. An
+ * agent harness that leaves stdin open but never writes to it would otherwise
+ * wait forever, which reads as a hang the agent cannot diagnose.
+ */
+exports.NON_TTY_ANSWER_TIMEOUT_MS = 10_000;
+/**
+ * NonInteractiveError reports a question that got no answer because stdin is
+ * not a terminal: input ended first, or nothing arrived in time.
+ *
+ * Before this error, end-of-input left readline's callback uncalled and the
+ * process exited 0 having done nothing (`find <url>` printed "Build playlist?
+ * [Y/n]" and quit). That looks like success to a caller that trusts exit
+ * codes, so the question fails loudly instead, naming what would answer it.
+ *
+ * Callers match on `name` (isNonInteractiveError), not `instanceof`: tests
+ * replace this module with a stub that does not export the class.
+ */
+class NonInteractiveError extends Error {
+    constructor(question, hint) {
+        const asked = question.trim();
+        super(`"${asked}" needs an answer, and none came: stdin is not a terminal.${hint ? ` ${hint}` : ''}`);
+        this.name = 'NonInteractiveError';
+    }
+}
+exports.NonInteractiveError = NonInteractiveError;
+/**
+ * isNonInteractiveError reports whether an error came from a question that
+ * got no answer on a non-terminal stdin.
+ *
+ * @param {unknown} error - Any caught value
+ * @returns {boolean} True for a NonInteractiveError
+ */
+function isNonInteractiveError(error) {
+    return error instanceof Error && error.name === 'NonInteractiveError';
+}
+/**
+ * createPrompt returns a prompt that asks on stdin and never waits silently.
+ *
+ * The readline interface opens on the first question, not at creation, so a
+ * command that never asks never attaches to stdin. A question rejects when
+ * input ends before an answer (on a terminal that is Ctrl-D; otherwise a
+ * NonInteractiveError), and, when stdin is not a terminal, when no answer
+ * arrives within NON_TTY_ANSWER_TIMEOUT_MS.
+ *
+ * @param {string} [nonInteractiveHint] - What answers the question without a
+ *   terminal (usually a flag); appended to the NonInteractiveError message
+ * @param {Object} [options] - Test seams
+ * @param {PromptInput} [options.input] - Stream to read answers from (default stdin)
+ * @param {number} [options.answerTimeoutMs] - Non-terminal wait bound
+ * @returns {Prompt} ask/close pair
+ */
+function createPrompt(nonInteractiveHint, options = {}) {
+    const input = options.input ?? process.stdin;
+    const timeoutMs = options.answerTimeoutMs ?? exports.NON_TTY_ANSWER_TIMEOUT_MS;
+    let rl = null;
+    const ask = async (question) => {
+        rl ??= readline.createInterface({ input, output: process.stdout });
+        const iface = rl;
+        return new Promise((resolve, reject) => {
+            let timer;
+            const settle = (finish) => {
+                clearTimeout(timer);
+                iface.off('close', onClose);
+                finish();
+            };
+            const noAnswer = () => input.isTTY
+                ? new Error('Input closed before an answer was given.')
+                : new NonInteractiveError(question, nonInteractiveHint);
+            const onClose = () => settle(() => reject(noAnswer()));
+            iface.once('close', onClose);
+            if (!input.isTTY) {
+                timer = setTimeout(() => settle(() => {
+                    reject(noAnswer());
+                    iface.close();
+                }), timeoutMs);
+            }
+            iface.question(chalk_1.default.yellow(question), (answer) => settle(() => resolve(answer.trim())));
         });
-    });
+    };
     return {
         ask,
-        close: () => rl.close(),
+        close: () => rl?.close(),
     };
 }
 async function promptYesNo(ask, question, defaultYes = true) {

package/dist/src/commands/play.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.playCommand = void 0;
+exports.displayCommand = void 0;
 exports.describeDiscoveryInput = describeDiscoveryInput;
 exports.probeDiscoveryUrlAsPlaylist = probeDiscoveryUrlAsPlaylist;
 const commander_1 = require("commander");
@@ -13,20 +13,21 @@ const config_1 = require("../config");
 const playlist_source_1 = require("../utilities/playlist-source");
 const playlist_cast_1 = require("../utilities/playlist-cast");
 const playlist_display_1 = require("./helpers/playlist-display");
+const hidden_alias_help_1 = require("./helpers/hidden-alias-help");
 /**
- * Human label for a discovery input that `play` cannot cast directly.
+ * Human label for a discovery input that `display` cannot cast directly.
  *
- * `play` casts an exact, already-playable source (a playlist file, a hosted
- * playlist URL, or a direct media/web URL). A marketplace URL, on-chain
+ * `display` casts an exact source it can send as it is (a playlist file, a
+ * hosted playlist URL, or a direct media/web URL). A marketplace URL, on-chain
  * coordinates, or a wallet address must be *resolved* through the indexer
- * first — that is `find`'s job. Returns a label for those inputs so `play`
+ * first — that is `find`'s job. Returns a label for those inputs so `display`
  * can redirect the user instead of silently wrapping, say, an Art Blocks
- * collection *page* as a web item. Returns null for anything `play` should
+ * collection *page* as a web item. Returns null for anything `display` should
  * handle itself (plain URLs and file paths parse to null here).
  *
  * A recognized-but-`unsupported` result (e.g. a legacy Art Blocks
  * `/projects/{id}` URL, or an unsupported-chain OpenSea link) is also a
- * discovery input — it's a marketplace URL, not a playable file — so it is
+ * discovery input — it's a marketplace URL, not a file it can send — so it is
  * redirected to `find` too, which surfaces the specific reason.
  */
 function describeDiscoveryInput(source) {
@@ -72,15 +73,21 @@ function describeDiscoveryInput(source) {
  * which wrongly redirected DP-1 feed playlist URLs
  * (https://feed.feralfile.com/api/v1/playlists/{slug}, exactly the URLs the
  * feed hands out) to `find`, which has no feed route either; the documented
- * "hosted playlist URL plays directly" contract was unreachable for them
+ * "hosted playlist URL displays directly" contract was unreachable for them
  * (found 2026-08-02 casting a published playlist to an FF1).
  *
  * Probing the document keeps both behaviors without a host allowlist: a URL
- * that serves DP-1 JSON (`dpVersion` marker) plays directly; a marketplace
+ * that serves DP-1 JSON (`dpVersion` marker) displays directly; a marketplace
  * *page* fails the probe (non-JSON, or JSON with no marker) and still
  * redirects to `find` instead of being wrapped as a web item. The probe
  * costs one fetch before a redirect, only for discovery inputs that are
  * http(s) URLs; coordinates and wallet addresses never hit the network.
+ *
+ * A URL that does not exist (404/410, no such host, a broken `.json` link)
+ * is refused here rather than redirected: the redirect also suggests
+ * `display --web`, which would cast the error page.
+ *
+ * @throws {Error} When the URL does not exist (refusalForLoadFailure)
  */
 async function probeDiscoveryUrlAsPlaylist(source) {
     if (!(0, playlist_source_1.isPlaylistSourceUrl)(source)) {
@@ -99,89 +106,63 @@ async function probeDiscoveryUrlAsPlaylist(source) {
             source: loaded.source,
         };
     }
-    catch {
+    catch (error) {
+        const refusal = (0, playlist_source_1.refusalForLoadFailure)(source.trim(), error);
+        if (refusal) {
+            throw refusal;
+        }
         return null;
     }
 }
-exports.playCommand = new commander_1.Command('play')
-    .description('Play a playlist or media URL on an FF1 device')
-    .argument('<source>', 'Playlist file, playlist URL, or media URL')
+/**
+ * resolveWebPageSource wraps `source` as a web page for `display --web`, without
+ * the discovery redirect or the playlist probe.
+ *
+ * `--web` exists because the discovery parser claims whole hosts: any page on
+ * feralfile.com, opensea.io, objkt.com and the like is redirected to `find`,
+ * and `find` rejects every page that is not an artwork it can resolve (a
+ * homepage, an exhibition overview, a profile). Before `--web` there was no
+ * way to put such a page on display; the two commands pointed at each other.
+ *
+ * @param {string} source - The URL the caller passed
+ * @returns {Promise<PlaySource>} A `media` source with a `text/html` item
+ * @throws {Error} When `source` is not an http(s) URL
+ */
+async function resolveWebPageSource(source) {
+    const url = source.trim();
+    if (!(0, playlist_source_1.isPlaylistSourceUrl)(url)) {
+        throw new Error(`--web takes an http(s) URL; got "${source}".`);
+    }
+    const note = await (0, playlist_source_1.checkWebPageUrl)(url);
+    return (0, playlist_source_1.buildMediaPlaySource)(url, { asWebPage: true, note });
+}
+/**
+ * displayCommand puts a playlist, media URL, or web page on an FF1.
+ *
+ * The verb for art is display, not play (B&F weekly 2026-11-03; Canon
+ * reference/naming-brand.md §3.4): people play games and video, they display
+ * art. `play` was this command's name, so it stays as an alias that existing
+ * scripts and agents keep calling; hiddenAliasHelp keeps it out of every help
+ * screen so help teaches only `display`. Do not drop the alias without a
+ * decision to break those callers.
+ */
+exports.displayCommand = new commander_1.Command('display')
+    .alias('play')
+    .configureHelp(hidden_alias_help_1.hiddenAliasHelp)
+    .description('Display a playlist file, playlist URL, media URL, or web page on an FF1 device')
+    .argument('<source>', 'Playlist file, playlist URL, or any media or web page URL')
     .option('-d, --device <name>', 'Device name (uses first device if not specified)')
-    .option('--skip-verify', 'Skip signature verification and auto-sign gating before playing; use only when you accept malformed envelopes')
+    .option('--web', 'Display the URL as a web page, even on a marketplace site where display would otherwise send you to find')
+    .option('--skip-verify', 'Skip signature verification and auto-sign gating before displaying; use only when you accept malformed envelopes')
     .action(async (source, options) => {
     try {
-        // `play` casts an exact playable source. A marketplace URL / on-chain
-        // coords / wallet must be resolved through the indexer first — redirect
-        // to `find` rather than silently wrapping the *page* as a web item.
-        // Exception: a discovery-classified URL that actually serves a DP-1
-        // playlist document (the discovery parser claims whole hosts, catching
-        // feed playlist URLs) plays directly — see probeDiscoveryUrlAsPlaylist.
-        const discovery = describeDiscoveryInput(source);
-        let probed = null;
-        if (discovery) {
-            probed = await probeDiscoveryUrlAsPlaylist(source);
-        }
-        if (discovery && !probed) {
-            console.error(chalk_1.default.red('\n`play` casts an exact playlist or media URL — it does not search marketplaces.'));
-            console.error(chalk_1.default.dim(`  "${source}" looks like ${discovery}, which needs to be resolved first.`));
-            const deviceFlag = options.device ? ` -d "${options.device}"` : '';
-            console.log(chalk_1.default.yellow(`\nTry:  ff-cli find "${source}" --play${deviceFlag}`));
-            process.exit(1);
-        }
-        // No explicit duration: a direct video/audio URL plays its natural
-        // length (DP-1 §4.1); static media uses config.defaultDuration.
-        const resolved = probed ?? (await (0, playlist_source_1.resolvePlaySource)(source));
-        const isPlaylistSource = resolved.kind === 'playlist';
-        const sourceLabel = isPlaylistSource
-            ? `${resolved.sourceType}: ${resolved.source}`
-            : resolved.source;
-        console.log(chalk_1.default.blue('\nPlay on FF1\n'));
-        if (!options.skipVerify && isPlaylistSource) {
-            console.log(chalk_1.default.cyan(`Verify playlist (${sourceLabel})`));
-        }
-        // A direct media/web URL is wrapped in an unsigned single-item playlist,
-        // so it must be signed before the verify gate; a loaded playlist is sent
-        // as-is. castPlaylist owns the sign → verify → send sequence.
-        // Resolve through getPlaylistConfig rather than reading config.playlist directly: it is the one
-        // place that knows a config value may still be the config.json.example placeholder, in which case a
-        // valid PLAYLIST_PRIVATE_KEY must win. Duplicating the `config || env` precedence here is what made
-        // this path sign with the template literal while every other signing path used the real key.
-        const privateKey = (0, config_1.getPlaylistConfig)().privateKey || undefined;
-        const result = await (0, playlist_cast_1.castPlaylist)(resolved.playlist, {
-            deviceName: options.device,
-            skipVerify: options.skipVerify,
-            requireSignature: resolved.kind === 'media',
-            signingKey: privateKey,
-        });
-        if (!result.success) {
-            if (result.stage === 'verify') {
-                (0, playlist_display_1.printPlaylistVerificationFailure)({ valid: false, error: result.error, details: result.details }, isPlaylistSource ? `source: ${sourceLabel}` : undefined);
-            }
-            else if (result.stage === 'sign') {
-                console.error(chalk_1.default.red(`\n${result.error}`));
-            }
-            else {
-                console.error(chalk_1.default.red('\nPlay failed:'), result.error);
-                if (result.deviceDetails) {
-                    console.error(chalk_1.default.dim(`  Details: ${result.deviceDetails}`));
-                }
-            }
-            process.exit(1);
-        }
-        if (result.verified) {
-            console.log(chalk_1.default.green(result.signed ? '✓ Signed and verified\n' : '✓ Verified\n'));
-        }
-        console.log(chalk_1.default.green('✓ Playing'));
-        if (result.deviceName) {
-            console.log(chalk_1.default.dim(`  Device: ${result.deviceName}`));
-        }
-        if (result.device) {
-            console.log(chalk_1.default.dim(`  Host: ${result.device}`));
-        }
-        console.log();
+        const resolved = options.web
+            ? await resolveWebPageSource(source)
+            : await resolveDefaultSource(source, options.device);
+        await castResolved(resolved, options);
     }
     catch (error) {
-        if ((0, playlist_source_1.isPlaylistSourceUrl)(source)) {
+        if (!options.web && (0, playlist_source_1.isPlaylistSourceUrl)(source)) {
             (0, playlist_display_1.printPlaylistSourceLoadFailure)(source, error);
         }
         else {
@@ -190,3 +171,100 @@ exports.playCommand = new commander_1.Command('play')
         process.exit(1);
     }
 });
+/**
+ * resolveDefaultSource resolves a `display` argument without `--web`: discovery
+ * inputs go to `find`, everything else loads as a playlist or wraps as media.
+ *
+ * `display` casts an exact source as it is. A marketplace URL / on-chain coords /
+ * wallet must be resolved through the indexer first, so it redirects to `find`
+ * rather than silently wrapping the *page* as a web item. Exception: a
+ * discovery-classified URL that actually serves a DP-1 playlist document (the
+ * discovery parser claims whole hosts, catching feed playlist URLs) displays
+ * directly; see probeDiscoveryUrlAsPlaylist. The redirect names `--web` too,
+ * for the caller who did mean the page.
+ *
+ * @param {string} source - The URL, path, or reference the caller passed
+ * @param {string} [device] - Device name, carried into the suggested command
+ * @returns {Promise<PlaySource>} What to cast; exits 1 on a discovery input
+ */
+async function resolveDefaultSource(source, device) {
+    const discovery = describeDiscoveryInput(source);
+    let probed = null;
+    if (discovery) {
+        probed = await probeDiscoveryUrlAsPlaylist(source);
+    }
+    if (discovery && !probed) {
+        console.error(chalk_1.default.red('\n`display` casts an exact playlist or media URL — it does not search marketplaces.'));
+        console.error(chalk_1.default.dim(`  "${source}" looks like ${discovery}, which needs to be resolved first.`));
+        const deviceFlag = device ? ` -d "${device}"` : '';
+        console.log(chalk_1.default.yellow(`\nTry:  ff-cli find "${source}" --display -y${deviceFlag}`));
+        if ((0, playlist_source_1.isPlaylistSourceUrl)(source)) {
+            console.log(chalk_1.default.dim(`To show the page itself:  ff-cli display --web "${source}"${deviceFlag}`));
+        }
+        process.exit(1);
+    }
+    // No explicit duration: a direct video/audio URL plays its natural
+    // length (DP-1 §4.1); static media uses config.defaultDuration.
+    return probed ?? (await (0, playlist_source_1.resolvePlaySource)(source));
+}
+/**
+ * castResolved signs (for a synthesized media playlist), verifies, and sends
+ * a resolved source, then reports the outcome. Exits 1 on any failure.
+ *
+ * @param {PlaySource} resolved - What to cast
+ * @param {Object} options - The `display` options
+ * @returns {Promise<void>}
+ */
+async function castResolved(resolved, options) {
+    const isPlaylistSource = resolved.kind === 'playlist';
+    const sourceLabel = isPlaylistSource
+        ? `${resolved.sourceType}: ${resolved.source}`
+        : resolved.source;
+    console.log(chalk_1.default.blue('\nDisplay on FF1\n'));
+    if (resolved.kind === 'media' && resolved.note) {
+        console.log(chalk_1.default.yellow(resolved.note));
+    }
+    if (!options.skipVerify && isPlaylistSource) {
+        console.log(chalk_1.default.cyan(`Verify playlist (${sourceLabel})`));
+    }
+    // A direct media/web URL is wrapped in an unsigned single-item playlist,
+    // so it must be signed before the verify gate; a loaded playlist is sent
+    // as-is. castPlaylist owns the sign → verify → send sequence.
+    // Resolve through getPlaylistConfig rather than reading config.playlist directly: it is the one
+    // place that knows a config value may still be the config.json.example placeholder, in which case a
+    // valid PLAYLIST_PRIVATE_KEY must win. Duplicating the `config || env` precedence here is what made
+    // this path sign with the template literal while every other signing path used the real key.
+    const privateKey = (0, config_1.getPlaylistConfig)().privateKey || undefined;
+    const result = await (0, playlist_cast_1.castPlaylist)(resolved.playlist, {
+        deviceName: options.device,
+        skipVerify: options.skipVerify,
+        requireSignature: resolved.kind === 'media',
+        signingKey: privateKey,
+    });
+    if (!result.success) {
+        if (result.stage === 'verify') {
+            (0, playlist_display_1.printPlaylistVerificationFailure)({ valid: false, error: result.error, details: result.details }, isPlaylistSource ? `source: ${sourceLabel}` : undefined);
+        }
+        else if (result.stage === 'sign') {
+            console.error(chalk_1.default.red(`\n${result.error}`));
+        }
+        else {
+            console.error(chalk_1.default.red('\nDisplay failed:'), result.error);
+            if (result.deviceDetails) {
+                console.error(chalk_1.default.dim(`  Details: ${result.deviceDetails}`));
+            }
+        }
+        process.exit(1);
+    }
+    if (result.verified) {
+        console.log(chalk_1.default.green(result.signed ? '✓ Signed and verified\n' : '✓ Verified\n'));
+    }
+    console.log(chalk_1.default.green('✓ Displaying'));
+    if (result.deviceName) {
+        console.log(chalk_1.default.dim(`  Device: ${result.deviceName}`));
+    }
+    if (result.device) {
+        console.log(chalk_1.default.dim(`  Host: ${result.device}`));
+    }
+    console.log();
+}