@feralfile/cli 2.10.0 → 3.0.0

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

@@ -81,6 +81,12 @@ function describeDiscoveryInput(source) {
  * 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
+ * `play --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 +105,51 @@ 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;
     }
 }
+/**
+ * resolveWebPageSource wraps `source` as a web page for `play --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 a wall; 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 });
+}
 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')
+    .description('Play 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('--web', 'Play the URL as a web page, even on a marketplace site where play would otherwise send you to find')
     .option('--skip-verify', 'Skip signature verification and auto-sign gating before playing; 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 +158,100 @@ exports.playCommand = new commander_1.Command('play')
         process.exit(1);
     }
 });
+/**
+ * resolveDefaultSource resolves a `play` argument without `--web`: discovery
+ * inputs go to `find`, everything else loads as a playlist or wraps as media.
+ *
+ * `play` casts an exact playable source. 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) plays
+ * 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`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 = device ? ` -d "${device}"` : '';
+        console.log(chalk_1.default.yellow(`\nTry:  ff-cli find "${source}" --play -y${deviceFlag}`));
+        if ((0, playlist_source_1.isPlaylistSourceUrl)(source)) {
+            console.log(chalk_1.default.dim(`To show the page itself:  ff-cli play --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 `play` 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('\nPlay 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('\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();
+}

package/dist/src/commands/setup.js

@@ -17,7 +17,61 @@ const prompt_1 = require("./helpers/prompt");
 const config_placeholders_1 = require("../utilities/config-placeholders");
 const ed25519_key_derive_1 = require("../utilities/ed25519-key-derive");
 const signing_key_source_1 = require("../utilities/signing-key-source");
+const signing_identity_1 = require("../utilities/signing-identity");
 const playlist_signing_role_1 = require("../utilities/playlist-signing-role");
+/**
+ * didKeyOrNull derives the signing identity for key material, or null when the
+ * material does not parse (a placeholder or corrupt value is not an identity
+ * anyone owns playlists with).
+ *
+ * @param {string} keyMaterial - Configured or supplied key material
+ * @returns {string | null} The did:key, or null
+ */
+function didKeyOrNull(keyMaterial) {
+    try {
+        return (0, signing_identity_1.playlistSigningDidKey)(keyMaterial);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * assertKeyReplacementAllowed refuses to replace a configured signing key with
+ * a different one unless the caller passed --force.
+ *
+ * The configured key is the curator identity that owns every playlist it
+ * published: `publish --replace` and `unpublish` only accept that key. setup
+ * keeps no copy of the old key, so replacing it silently is permanent. This
+ * happened in practice: an agent ran the documented `setup --non-interactive
+ * --generate-key` on a machine that was already configured and swapped its
+ * owner key without a word. The interactive "Keep existing signing key?"
+ * question is its own confirmation and does not come through here.
+ *
+ * "Configured" means the identity signing uses today: the config key, or
+ * PLAYLIST_PRIVATE_KEY when config holds none. A config key always wins over
+ * the environment (getPlaylistConfig), so writing one would mask an
+ * environment identity just as surely as overwriting a config key.
+ *
+ * @param {string} currentKey - Effective key material (may be a placeholder or empty)
+ * @param {string} nextKey - Key material setup is about to write
+ * @param {string} flag - The flag that asked for the change, named in the error
+ * @param {boolean} force - Whether --force was passed
+ * @param {string} [source] - Where currentKey came from, when not config.json
+ * @throws {Error} When an existing, different identity would be replaced without --force
+ */
+function assertKeyReplacementAllowed(currentKey, nextKey, flag, force, source) {
+    if (force || (0, config_files_1.isMissingConfigValue)(currentKey)) {
+        return;
+    }
+    const currentDid = didKeyOrNull(currentKey);
+    if (currentDid === null || currentDid === didKeyOrNull(nextKey)) {
+        return;
+    }
+    throw new Error(`A signing key is already configured (${currentDid}${source ? `, from ${source}` : ''}). ` +
+        'It owns the playlists you published; ' +
+        'replacing it means you can no longer replace or unpublish them. ' +
+        `Re-run without ${flag} to keep it, or add --force to replace it.`);
+}
 /** Generate a fresh Ed25519 signing key as base64 PKCS#8 DER (the recommended form). */
 function generateSigningKeyBase64() {
     const keyPair = crypto_1.default.generateKeyPairSync('ed25519');
@@ -28,7 +82,8 @@ exports.setupCommand = new commander_1.Command('setup')
     .option('-y, --non-interactive', 'Run without prompts (for agents/CI); uses flags and safe defaults. Auto-enabled when stdin is not a TTY.')
     .option('--key <privateKey>', 'Signing key material (base64 PKCS#8 DER, 32-byte seed as hex/base64, or PEM)')
     .option('--key-file <path>', 'Read the signing key from this file instead of the command line (preferred for provisioning)')
-    .option('--generate-key', 'Generate a new Ed25519 signing key')
+    .option('--generate-key', 'Generate a new Ed25519 signing key (only when none is configured)')
+    .option('--force', 'Allow --generate-key, --key, or --key-file to replace a configured signing key (it owns your published playlists)')
     .option('--role <role>', `Signing role (${playlist_signing_role_1.DP1_PLAYLIST_SIGNING_ROLES.join(', ')})`)
     .option('--device-host <host>', 'FF1 device host, e.g. http://192.168.1.50:1111 (skips mDNS discovery)')
     .option('--device-name <name>', 'Friendly name for the device')
@@ -84,22 +139,38 @@ exports.setupCommand = new commander_1.Command('setup')
         const currentRole = config.playlist?.role || '';
         let signingKey = currentKey;
         let signingRole = currentRole;
+        // The identity signing uses today. With no usable key in config, signing falls back to
+        // PLAYLIST_PRIVATE_KEY, and a config key written now would silently take its place.
+        const envKey = process.env.PLAYLIST_PRIVATE_KEY?.trim() || '';
+        const keyFromEnv = (0, config_files_1.isMissingConfigValue)(currentKey) && !(0, config_files_1.isMissingConfigValue)(envKey);
+        const effectiveKey = keyFromEnv ? envKey : currentKey;
+        const keySource = keyFromEnv ? 'PLAYLIST_PRIVATE_KEY' : undefined;
+        const force = Boolean(options.force);
         // Already resolved and validated above, before any file was created.
         if (explicitKey !== undefined) {
+            assertKeyReplacementAllowed(effectiveKey, explicitKey.material, explicitKey.flag, force, keySource);
             signingKey = explicitKey.material;
         }
         else if (nonInteractive) {
             // Key precedence with no explicit key: --generate-key, then keep an
             // existing usable key, otherwise generate one so signing works.
-            if (options.generateKey || (0, config_files_1.isMissingConfigValue)(currentKey)) {
-                signingKey = generateSigningKeyBase64();
+            if (options.generateKey || (0, config_files_1.isMissingConfigValue)(effectiveKey)) {
+                const generated = generateSigningKeyBase64();
+                assertKeyReplacementAllowed(effectiveKey, generated, '--generate-key', force, keySource);
+                signingKey = generated;
                 console.log(chalk_1.default.dim('Generated a new Ed25519 signing key.'));
             }
+            else if (keyFromEnv) {
+                console.log(chalk_1.default.dim('Signing with PLAYLIST_PRIVATE_KEY; config.json keeps no key.'));
+            }
         }
         else {
-            if ((0, config_files_1.isMissingConfigValue)(currentKey)) {
+            if ((0, config_files_1.isMissingConfigValue)(effectiveKey)) {
                 signingKey = generateSigningKeyBase64();
             }
+            else if (keyFromEnv) {
+                console.log(chalk_1.default.dim('Signing with PLAYLIST_PRIVATE_KEY; config.json keeps no key.'));
+            }
             else {
                 const ask = getAsk();
                 const keepKey = await (0, prompt_1.promptYesNo)(ask, 'Keep existing signing key?', true);
@@ -109,7 +180,9 @@ exports.setupCommand = new commander_1.Command('setup')
                 }
             }
         }
-        if (signingKey) {
+        // The role applies to whichever identity signs, including PLAYLIST_PRIVATE_KEY when
+        // config keeps no key; skipping it there silently dropped --role.
+        if (signingKey || keyFromEnv) {
             if (nonInteractive) {
                 // Role precedence: --role, then existing role, then 'agent'.
                 try {
@@ -139,7 +212,9 @@ exports.setupCommand = new commander_1.Command('setup')
             }
             config.playlist = {
                 ...(config.playlist || {}),
-                privateKey: signingKey,
+                // With the identity in PLAYLIST_PRIVATE_KEY, keep whatever config held (empty or a
+                // placeholder) so the environment key keeps signing.
+                privateKey: signingKey || (config.playlist?.privateKey ?? ''),
                 role: signingRole,
             };
         }

package/dist/src/commands/status.js

@@ -61,7 +61,10 @@ exports.statusCommand = new commander_1.Command('status')
         }
         const configPath = await (0, config_files_1.resolveExistingConfigPath)();
         if (!configPath) {
-            console.log(chalk_1.default.red('config.json not found'));
+            // Name both places looked: when a caller's environment points the user config somewhere
+            // unexpected (a sandboxed HOME with XDG_CONFIG_HOME still set), the path is the clue.
+            const { localPath, userPath } = (0, config_1.getConfigPaths)();
+            console.log(chalk_1.default.red(`config.json not found (looked in ${localPath} and ${userPath})`));
             console.log(chalk_1.default.dim('Run: ff-cli setup'));
             // PLAYLIST_PRIVATE_KEY is a supported signing source on its own, and the did:key it implies is
             // the one value a user must know before they can write a publishable playlist — it has to be

package/dist/src/config.js

@@ -11,6 +11,7 @@ exports.getPlaylistConfig = getPlaylistConfig;
 exports.getFeedConfig = getFeedConfig;
 exports.getFF1DeviceConfig = getFF1DeviceConfig;
 exports.getFF1RelayerConfig = getFF1RelayerConfig;
+exports.getTokenSourceConfig = getTokenSourceConfig;
 exports.validateConfig = validateConfig;
 exports.createSampleConfig = createSampleConfig;
 const fs_1 = __importDefault(require("fs"));
@@ -276,6 +277,93 @@ function resolveFF1RelayerConfig(config) {
         apiKey: apiKey || undefined,
     };
 }
+const TOKEN_SOURCES = ['raster', 'indexer'];
+const DEFAULT_TOKEN_SOURCE = 'indexer';
+const DEFAULT_IPFS_GATEWAY_FERAL_FILE = 'https://ipfs.feralfile.com/ipfs/';
+const DEFAULT_IPFS_GATEWAY = 'https://ipfs.filebase.io/ipfs/';
+/**
+ * Get the token source selection using repository config priority.
+ *
+ * `config.json` wins over environment variables, which win over the defaults.
+ * The Feral File indexer is the default vendor; `raster` is opt-in while
+ * Raster's data bugs (feral-file#3546) are open. There is no fallback between
+ * the two at runtime: one vendor answers a whole run.
+ */
+function getTokenSourceConfig() {
+    return resolveTokenSourceConfig(getConfig());
+}
+/** Resolve and validate the effective token source configuration. */
+function resolveTokenSourceConfig(config) {
+    const source = resolveTokenSourceName(config);
+    const gateways = resolveIpfsGatewayFields(config);
+    return {
+        source,
+        ipfsGateways: {
+            feralFile: normalizeIpfsGateway(gateways.feralFile ||
+                process.env.IPFS_GATEWAY_FERAL_FILE ||
+                DEFAULT_IPFS_GATEWAY_FERAL_FILE, 'ipfsGateways.feralFile'),
+            default: normalizeIpfsGateway(gateways.default || process.env.IPFS_GATEWAY_DEFAULT || DEFAULT_IPFS_GATEWAY, 'ipfsGateways.default'),
+        },
+    };
+}
+/** resolveTokenSourceName picks the vendor name, rejecting anything outside TOKEN_SOURCES. */
+function resolveTokenSourceName(config) {
+    const configured = config.tokenSource;
+    if (configured !== undefined && typeof configured !== 'string') {
+        throw new Error(`tokenSource must be one of: ${TOKEN_SOURCES.join(', ')}`);
+    }
+    const candidate = (configured || process.env.FF_TOKEN_SOURCE || '')
+        .trim()
+        .toLowerCase();
+    if (!candidate) {
+        return DEFAULT_TOKEN_SOURCE;
+    }
+    if (!TOKEN_SOURCES.includes(candidate)) {
+        throw new Error(`tokenSource must be one of: ${TOKEN_SOURCES.join(', ')}`);
+    }
+    return candidate;
+}
+/** resolveIpfsGatewayFields type-checks the `ipfsGateways` block without resolving defaults. */
+function resolveIpfsGatewayFields(config) {
+    const configured = config.ipfsGateways;
+    if (configured === undefined) {
+        return {};
+    }
+    if (configured === null || typeof configured !== 'object' || Array.isArray(configured)) {
+        throw new Error('ipfsGateways must be an object');
+    }
+    const fields = configured;
+    for (const key of ['feralFile', 'default']) {
+        if (fields[key] !== undefined && typeof fields[key] !== 'string') {
+            throw new Error(`ipfsGateways.${key} must be a string`);
+        }
+    }
+    return { feralFile: fields.feralFile, default: fields.default };
+}
+/**
+ * normalizeIpfsGateway validates a gateway and returns it in `https://host/ipfs/` form.
+ *
+ * A bare origin is accepted because that is how gateways are usually quoted;
+ * the `/ipfs/` path is what a CID is appended to, so it is added when absent
+ * and a trailing slash is guaranteed so callers can concatenate.
+ */
+function normalizeIpfsGateway(value, label) {
+    let parsed;
+    try {
+        parsed = new URL(value.trim());
+    }
+    catch {
+        throw new Error(`${label} must be a valid HTTP(S) URL`);
+    }
+    if (!['http:', 'https:'].includes(parsed.protocol)) {
+        throw new Error(`${label} must be a valid HTTP(S) URL`);
+    }
+    const path = parsed.pathname.replace(/\/+$/, '');
+    parsed.pathname = path.endsWith('/ipfs') ? `${path}/` : `${path}/ipfs/`;
+    parsed.search = '';
+    parsed.hash = '';
+    return parsed.toString();
+}
 /**
  * Validate configuration
  *
@@ -341,6 +429,12 @@ function validateConfig() {
         catch (error) {
             errors.push(error.message);
         }
+        try {
+            resolveTokenSourceConfig(config);
+        }
+        catch (error) {
+            errors.push(error.message);
+        }
         return {
             valid: errors.length === 0,
             errors,

package/dist/src/main.js

@@ -4,6 +4,7 @@
  * Builds DP-1 playlists deterministically from structured parameters.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIREMENT_TYPES = void 0;
 exports.validateRequirements = validateRequirements;
 exports.applyPlaylistDefaults = applyPlaylistDefaults;
 exports.buildPlaylistDirect = buildPlaylistDirect;
@@ -18,10 +19,20 @@ process.emitWarning = function (warning, type, ctor) {
     }
     return originalEmitWarning.apply(this, [warning, type, ctor]);
 };
-const config_1 = require("./config");
 // Lazy load utilities to avoid circular dependencies
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const getUtilities = () => require('./utilities');
+/**
+ * REQUIREMENT_TYPES lists every requirement `build` accepts, in the order
+ * `build --help` documents them. Kept beside validateRequirements so a new
+ * branch there and this list change together.
+ */
+exports.REQUIREMENT_TYPES = [
+    'build_playlist',
+    'query_address',
+    'fetch_feed',
+    'feral_file_artwork',
+];
 /**
  * Validate and apply constraints to requirements
  *
@@ -103,7 +114,8 @@ function validateRequirements(requirements) {
                 };
             }
         }
-        throw new Error(`Requirement ${index + 1}: invalid type "${req.type}"`);
+        throw new Error(`Requirement ${index + 1}: invalid type "${req.type}". ` +
+            `Valid types: ${exports.REQUIREMENT_TYPES.join(', ')} (see ff-cli build --help).`);
     });
 }
 /**
@@ -140,8 +152,5 @@ async function buildPlaylistDirect(params, options = {}) {
     const requirements = validateRequirements(params.requirements);
     const playlistSettings = applyPlaylistDefaults(params.playlistSettings);
     const utilities = getUtilities();
-    const config = (0, config_1.getConfig)();
-    // Initialize utilities with config (indexer endpoint, API key, etc.)
-    utilities.initializeUtilities(config);
     return await utilities.buildPlaylistDirect({ requirements, playlistSettings }, options);
 }