ff1-cli 1.0.2 → 1.0.3

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

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * FF1 device compatibility helpers for command preflight checks.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfiguredDevice = resolveConfiguredDevice;
+exports.assertFF1CommandCompatibility = assertFF1CommandCompatibility;
+const config_1 = require("../config");
+const logger = __importStar(require("../logger"));
+const FF1_COMMAND_POLICIES = {
+    displayPlaylist: {
+        minimumVersion: '1.0.0',
+    },
+    sshAccess: {
+        minimumVersion: '1.0.9',
+    },
+};
+/**
+ * Load and validate the configured FF1 device selected by name.
+ *
+ * @param {string} [deviceName] - Optional device name, exact match required
+ * @param {Object} [options] - Optional dependency overrides
+ * @param {Function} [options.getFF1DeviceConfigFn] - Optional config loader override
+ * @returns {FF1DeviceSelectionResult} Selected device or reason for failure
+ * @throws {Error} Never throws; malformed configuration is returned as an error result
+ * @example
+ * const result = resolveConfiguredDevice('Living Room');
+ */
+function resolveConfiguredDevice(deviceName, options = {}) {
+    const getFF1DeviceConfigFn = options.getFF1DeviceConfigFn || config_1.getFF1DeviceConfig;
+    const deviceConfig = getFF1DeviceConfigFn();
+    if (!deviceConfig.devices || deviceConfig.devices.length === 0) {
+        return {
+            success: false,
+            error: 'No FF1 devices configured. Add devices to config.json under "ff1Devices"',
+        };
+    }
+    let device = deviceConfig.devices[0];
+    if (deviceName) {
+        device = deviceConfig.devices.find((item) => item.name === deviceName);
+        if (!device) {
+            const availableNames = deviceConfig.devices
+                .map((item) => item.name)
+                .filter(Boolean)
+                .join(', ');
+            return {
+                success: false,
+                error: `Device "${deviceName}" not found. Available devices: ${availableNames || 'none with names'}`,
+            };
+        }
+        logger.info(`Found device by name: ${deviceName}`);
+    }
+    else {
+        logger.info('Using first configured device');
+    }
+    if (!device.host) {
+        return {
+            success: false,
+            error: 'Invalid device configuration: must include host',
+        };
+    }
+    return {
+        success: true,
+        device,
+    };
+}
+/**
+ * Ensure the target device supports the requested FF1 command.
+ *
+ * @param {Object} device - FF1 device configuration
+ * @param {FF1Command} command - Command to execute
+ * @param {Object} [options] - Optional dependency overrides
+ * @param {Function} [options.fetchFn] - Optional fetch implementation
+ * @returns {Promise<FF1CompatibilityResult>} Compatibility result
+ * @throws {Error} Never throws; network and parsing failures produce a compatible result
+ * @example
+ * const result = await assertFF1CommandCompatibility(device, 'displayPlaylist');
+ */
+async function assertFF1CommandCompatibility(device, command, options = {}) {
+    const fetchFn = options.fetchFn || globalThis.fetch.bind(globalThis);
+    const policy = getCommandPolicy(command);
+    const versionResult = await detectFF1VersionSafely(device.host, buildVersionHeaders(device), fetchFn);
+    return resolveCompatibility(device, command, policy, versionResult);
+}
+/**
+ * Return command compatibility requirements.
+ *
+ * @param {FF1Command} command - Command to check
+ * @returns {FF1CommandPolicy} Policy metadata
+ * @example
+ * getCommandPolicy('sshAccess'); // { minimumVersion: '1.0.0' }
+ */
+function getCommandPolicy(command) {
+    return FF1_COMMAND_POLICIES[command];
+}
+/**
+ * Detect FF1 version and recover compatibility when detection fails.
+ *
+ * @param {string} host - Device host URL
+ * @param {Object} headers - Request headers
+ * @param {Function} fetchFn - Fetch implementation
+ * @returns {Promise<FF1VersionProbe | null>} Detected version metadata
+ */
+async function detectFF1VersionSafely(host, headers, fetchFn) {
+    try {
+        return await detectFF1Version(host, headers, fetchFn);
+    }
+    catch (error) {
+        logger.debug('FF1 version detection failed; continuing with command', error.message);
+        return null;
+    }
+}
+/**
+ * Resolve final compatibility decision from detected version and policy.
+ *
+ * @param {FF1Device} device - Target device
+ * @param {FF1Command} command - Command requested
+ * @param {FF1CommandPolicy} policy - Version policy
+ * @param {FF1VersionProbe | null} versionResult - Detected version probe
+ * @returns {FF1CompatibilityResult} Compatibility decision
+ */
+function resolveCompatibility(device, command, policy, versionResult) {
+    if (!versionResult) {
+        logger.warn(`Could not verify FF1 OS version for ${device.name || device.host}`);
+        return { compatible: true };
+    }
+    const normalizedVersion = normalizeVersion(versionResult.version);
+    if (!normalizedVersion) {
+        return {
+            compatible: true,
+            version: versionResult.version,
+        };
+    }
+    if (compareVersions(normalizedVersion, policy.minimumVersion) < 0) {
+        return {
+            compatible: false,
+            version: normalizedVersion,
+            error: `Unsupported FF1 OS ${normalizedVersion} for ${command}. FF1 OS must be ${policy.minimumVersion} or newer.`,
+        };
+    }
+    return {
+        compatible: true,
+        version: normalizedVersion,
+    };
+}
+/**
+ * Detect FF1 OS version via POST /api/cast with getDeviceStatus command.
+ *
+ * Reads `message.installedVersion` from the device status response.
+ *
+ * @param {string} host - Device host URL
+ * @param {Record<string, string>} headers - Request headers (e.g. API-KEY)
+ * @param {FetchFunction} fetchFn - Fetch implementation
+ * @returns {Promise<FF1VersionProbe | null>} Version probe or null if unavailable
+ * @example
+ * const probe = await detectFF1Version('http://ff1.local', {}, fetch);
+ */
+async function detectFF1Version(host, headers, fetchFn) {
+    try {
+        const response = await fetchFn(`${host}/api/cast`, {
+            method: 'POST',
+            headers: { ...headers, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ command: 'getDeviceStatus', request: {} }),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const data = (await response.json());
+        const version = data?.message?.installedVersion;
+        if (!version) {
+            return null;
+        }
+        return { version };
+    }
+    catch (_error) {
+        return null;
+    }
+}
+/**
+ * Build headers shared by cast requests.
+ *
+ * @param {FF1Device} device - Target device
+ * @returns {Record<string, string>} Headers map
+ * @example
+ * const headers = buildVersionHeaders(device);
+ */
+function buildVersionHeaders(device) {
+    const headers = {};
+    if (device.apiKey) {
+        headers['API-KEY'] = device.apiKey;
+    }
+    return headers;
+}
+/**
+ * Parse and normalize a version string to x.y.z format.
+ *
+ * @param {string} version - Raw version string
+ * @returns {string | null} Normalized semver-like version
+ * @example
+ * normalizeVersion('v1.2') // '1.2.0'
+ */
+function normalizeVersion(version) {
+    const raw = version.trim();
+    const match = raw.match(/(?:v)?(\d+)\.(\d+)(?:\.(\d+))?/);
+    if (!match) {
+        return null;
+    }
+    const major = match[1];
+    const minor = match[2];
+    const patch = match[3] || '0';
+    return `${major}.${minor}.${patch}`;
+}
+/**
+ * Compare two semantic versions in x.y.z format.
+ *
+ * @param {string} left - First version
+ * @param {string} right - Second version
+ * @returns {number} 1 if left > right, -1 if left < right, 0 if equal
+ * @example
+ * compareVersions('1.2.1', '1.2.0'); // 1
+ */
+function compareVersions(left, right) {
+    const leftParts = left.split('.').map((value) => Number.parseInt(value, 10));
+    const rightParts = right.split('.').map((value) => Number.parseInt(value, 10));
+    for (let i = 0; i < 3; i++) {
+        const leftPart = leftParts[i] || 0;
+        const rightPart = rightParts[i] || 0;
+        if (leftPart > rightPart) {
+            return 1;
+        }
+        if (leftPart < rightPart) {
+            return -1;
+        }
+    }
+    return 0;
+}

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

@@ -38,8 +38,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sendPlaylistToDevice = sendPlaylistToDevice;
-const config_1 = require("../config");
 const logger = __importStar(require("../logger"));
+const ff1_compatibility_1 = require("./ff1-compatibility");
 /**
  * Send a DP1 playlist to an FF1 device using the cast API
  *
@@ -80,38 +80,20 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
                 error: 'Invalid playlist: must provide a valid DP1 playlist object',
             };
         }
-        // Get device configuration
-        const deviceConfig = (0, config_1.getFF1DeviceConfig)();
-        if (!deviceConfig.devices || deviceConfig.devices.length === 0) {
+        const resolved = (0, ff1_compatibility_1.resolveConfiguredDevice)(deviceName);
+        if (!resolved.success || !resolved.device) {
             return {
                 success: false,
-                error: 'No FF1 devices configured. Please add devices to config.json under "ff1Devices"',
+                error: resolved.error || 'FF1 device is not configured correctly',
             };
         }
-        // Find device by name if provided, otherwise use first device
-        let device;
-        if (deviceName) {
-            device = deviceConfig.devices.find((d) => d.name === deviceName);
-            if (!device) {
-                const availableNames = deviceConfig.devices
-                    .map((d) => d.name)
-                    .filter(Boolean)
-                    .join(', ');
-                return {
-                    success: false,
-                    error: `Device "${deviceName}" not found. Available devices: ${availableNames || 'none with names'}`,
-                };
-            }
-            logger.info(`Found device by name: ${deviceName}`);
-        }
-        else {
-            device = deviceConfig.devices[0];
-            logger.info('Using first configured device');
-        }
-        if (!device.host) {
+        const device = resolved.device;
+        const compatibility = await (0, ff1_compatibility_1.assertFF1CommandCompatibility)(device, 'displayPlaylist');
+        if (!compatibility.compatible) {
             return {
                 success: false,
-                error: 'Invalid device configuration: must include host',
+                error: compatibility.error || 'FF1 OS does not support playlist casting',
+                details: compatibility.version ? `Detected version ${compatibility.version}` : undefined,
             };
         }
         logger.info(`Sending playlist to FF1 device: ${device.host}`);

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

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverFF1Devices = discoverFF1Devices;
+const bonjour_service_1 = require("bonjour-service");
+const DEFAULT_TIMEOUT_MS = 2000;
+/**
+ * Normalize mDNS TXT records to string values.
+ *
+ * @param {Record<string, unknown> | undefined} record - Raw TXT record object from mDNS
+ * @returns {Record<string, string>} Normalized TXT records
+ * @example
+ * normalizeTxtRecords({ id: 'ff1-1234', name: 'Studio FF1' });
+ */
+function normalizeTxtRecords(record) {
+    if (!record) {
+        return {};
+    }
+    return Object.entries(record).reduce((accumulator, [key, value]) => {
+        if (typeof value === 'string') {
+            accumulator[key] = value;
+            return accumulator;
+        }
+        if (Buffer.isBuffer(value)) {
+            accumulator[key] = value.toString('utf8');
+            return accumulator;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean') {
+            accumulator[key] = String(value);
+        }
+        return accumulator;
+    }, {});
+}
+/**
+ * Normalize mDNS hostnames by trimming a trailing dot.
+ *
+ * @param {string} host - Raw host from mDNS results
+ * @returns {string} Normalized host
+ * @example
+ * normalizeMdnsHost('ff1-1234.local.');
+ */
+function normalizeMdnsHost(host) {
+    return host.endsWith('.') ? host.slice(0, -1) : host;
+}
+/**
+ * Extract a hostname-based ID from an mDNS host when possible.
+ *
+ * @param {string} host - Normalized mDNS host
+ * @returns {string} Hostname-based ID when available
+ * @example
+ * getHostnameId('ff1-03vdu3x1.local');
+ */
+function getHostnameId(host) {
+    if (!host) {
+        return '';
+    }
+    if (host.includes(':')) {
+        return '';
+    }
+    if (/^[0-9.]+$/.test(host)) {
+        return '';
+    }
+    if (host.endsWith('.local')) {
+        return host.split('.')[0] || '';
+    }
+    if (!host.includes('.')) {
+        return host;
+    }
+    return '';
+}
+/**
+ * Discover FF1 devices via mDNS using the `_ff1._tcp` service.
+ *
+ * @param {Object} [options] - Discovery options
+ * @param {number} [options.timeoutMs] - How long to browse before returning results
+ * @returns {Promise<FF1DiscoveryResult>} Discovered FF1 devices and optional error
+ * @throws {Error} Never throws; returns empty list on errors
+ * @example
+ * const result = await discoverFF1Devices({ timeoutMs: 2000 });
+ */
+async function discoverFF1Devices(options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return new Promise((resolve) => {
+        let resolved = false;
+        const finish = (result, error) => {
+            if (resolved) {
+                return;
+            }
+            resolved = true;
+            resolve({ devices: result, error });
+        };
+        try {
+            const bonjour = new bonjour_service_1.Bonjour();
+            const devices = new Map();
+            const browser = bonjour.find({ type: 'ff1', protocol: 'tcp' });
+            const finalize = (error) => {
+                try {
+                    browser.stop();
+                    bonjour.destroy();
+                }
+                catch (_error) {
+                    finish([], error || 'mDNS discovery failed while stopping the browser');
+                    return;
+                }
+                const result = Array.from(devices.values()).sort((left, right) => left.name.localeCompare(right.name));
+                finish(result, error);
+            };
+            const timeoutHandle = setTimeout(() => finalize(), timeoutMs);
+            browser.on('up', (service) => {
+                const host = normalizeMdnsHost(service.host || service.fqdn || '');
+                if (!host) {
+                    return;
+                }
+                const port = service.port || 1111;
+                const txt = normalizeTxtRecords(service.txt);
+                const name = txt.name || service.name || txt.id || host;
+                const hostId = getHostnameId(host);
+                const id = hostId || txt.id || undefined;
+                const key = `${host}:${port}`;
+                devices.set(key, {
+                    name,
+                    host,
+                    port,
+                    id,
+                    fqdn: service.fqdn,
+                    txt,
+                });
+            });
+            browser.on('error', (error) => {
+                clearTimeout(timeoutHandle);
+                const message = error instanceof Error ? error.message : String(error);
+                try {
+                    browser.stop();
+                    bonjour.destroy();
+                }
+                catch (_error) {
+                    finish([], `mDNS discovery failed: ${message || 'failed to stop browser after error'}`);
+                    return;
+                }
+                finalize(`mDNS discovery failed: ${message || 'discovery error'}`);
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            finish([], `mDNS discovery failed: ${message || 'discovery error'}`);
+        }
+    });
+}

package/dist/src/utilities/functions.js

@@ -39,6 +39,7 @@ const chalk = require('chalk');
 const playlistBuilder = require('./playlist-builder');
 const ff1Device = require('./ff1-device');
 const domainResolver = require('./domain-resolver');
+const logger = require('../logger');
 /**
  * Build DP1 v1.0.0 compliant playlist
  *
@@ -112,7 +113,7 @@ async function sendPlaylistToDevice(params) {
  * console.log(result.domainMap); // { 'vitalik.eth': '0x...', 'alice.tez': 'tz...' }
  */
 async function resolveDomains(params) {
-    const { domains, displayResults = true } = params;
+    const { domains, displayResults = false } = params;
     if (!domains || !Array.isArray(domains) || domains.length === 0) {
         const error = 'No domains provided for resolution';
         console.error(chalk.red(`\n${error}`));
@@ -158,7 +159,7 @@ async function verifyPlaylist(params) {
             error: 'No playlist provided for verification',
         };
     }
-    console.log(chalk.cyan('\nValidate playlist'));
+    logger.verbose(chalk.cyan('\nValidate playlist'));
     // Dynamic import to avoid circular dependency
     const playlistVerifier = await Promise.resolve().then(() => __importStar(require('./playlist-verifier')));
     const verify = playlistVerifier.verifyPlaylist ||
@@ -172,14 +173,14 @@ async function verifyPlaylist(params) {
     }
     const result = verify(playlist);
     if (result.valid) {
-        console.log(chalk.green('Playlist looks good'));
+        logger.verbose(chalk.green('Playlist looks good'));
         if (playlist.title) {
-            console.log(chalk.dim(`  Title: ${playlist.title}`));
+            logger.verbose(chalk.dim(`  Title: ${playlist.title}`));
         }
         if (playlist.items) {
-            console.log(chalk.dim(`  Items: ${playlist.items.length}`));
+            logger.verbose(chalk.dim(`  Items: ${playlist.items.length}`));
         }
-        console.log();
+        logger.verbose();
     }
     else {
         console.error(chalk.red('Playlist has issues'));
@@ -237,26 +238,7 @@ async function verifyAddresses(params) {
     }
     const result = validateAddresses(addresses);
     // Display results
-    if (result.valid) {
-        console.log(chalk.green('\n✓ All addresses are valid'));
-        result.results.forEach((r) => {
-            const typeLabel = r.type === 'ethereum'
-                ? 'Ethereum'
-                : r.type === 'ens'
-                    ? 'ENS Domain'
-                    : r.type === 'tezos-domain'
-                        ? 'Tezos Domain'
-                        : r.type === 'contract'
-                            ? 'Tezos Contract'
-                            : 'Tezos User';
-            console.log(chalk.dim(`  • ${r.address} (${typeLabel})`));
-            if (r.normalized) {
-                console.log(chalk.dim(`    Checksummed: ${r.normalized}`));
-            }
-        });
-        console.log();
-    }
-    else {
+    if (!result.valid) {
         console.error(chalk.red('\nAddress validation failed'));
         result.errors.forEach((err) => {
             console.error(chalk.red(`  • ${err}`));

package/dist/src/utilities/index.js

@@ -8,6 +8,8 @@ const feedFetcher = require('./feed-fetcher');
 const playlistBuilder = require('./playlist-builder');
 const functions = require('./functions');
 const domainResolver = require('./domain-resolver');
+const logger = require('../logger');
+const printedTokenCountKeys = new Set();
 /**
  * Initialize utilities with configuration
  *
@@ -94,7 +96,11 @@ async function queryTokensByAddress(ownerAddress, quantity, duration = 10) {
         if (typeof quantity === 'number' && selectedTokens.length > quantity) {
             selectedTokens = shuffleArray([...selectedTokens]).slice(0, quantity);
         }
-        console.log(chalk.dim(`Got ${selectedTokens.length} token(s)`));
+        const tokenCountKey = `${ownerAddress}|${quantity ?? 'all'}|${duration}`;
+        if (!printedTokenCountKeys.has(tokenCountKey)) {
+            console.log(chalk.dim(`Got ${selectedTokens.length} token(s)`));
+            printedTokenCountKeys.add(tokenCountKey);
+        }
         // Convert tokens to DP1 items
         const items = [];
         let skippedCount = 0;
@@ -147,10 +153,10 @@ async function queryRequirement(requirement, duration = 10) {
     if (type === 'query_address') {
         // Check if ownerAddress is a domain name (.eth or .tez)
         if (ownerAddress && (ownerAddress.endsWith('.eth') || ownerAddress.endsWith('.tez'))) {
-            console.log(chalk.cyan(`\nResolving domain ${ownerAddress}...`));
+            logger.verbose(chalk.cyan(`\nResolving domain ${ownerAddress}...`));
             const resolution = await domainResolver.resolveDomain(ownerAddress);
             if (resolution.resolved && resolution.address) {
-                console.log(chalk.dim(`  ${resolution.domain} → ${resolution.address}`));
+                console.log(chalk.green(`${resolution.domain} → ${resolution.address}`));
                 // Use resolved address instead of domain
                 return await queryTokensByAddress(resolution.address, quantity, duration);
             }

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

@@ -38,7 +38,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.confirmPlaylistForSending = confirmPlaylistForSending;
 const chalk_1 = __importDefault(require("chalk"));
-const fs_1 = require("fs");
+const playlist_source_1 = require("./playlist-source");
 /**
  * Get available FF1 devices from config
  *
@@ -77,7 +77,7 @@ async function getAvailableDevices() {
  * Reads the playlist file, validates it against DP-1 spec,
  * and returns confirmation result for user review.
  *
- * @param {string} filePath - Path to playlist file
+ * @param {string} filePath - Playlist file path or URL
  * @param {string} [deviceName] - Device name (optional)
  * @returns {Promise<PlaylistSendConfirmation>} Validation result
  */
@@ -90,38 +90,57 @@ async function confirmPlaylistForSending(filePath, deviceName) {
         console.error(chalk_1.default.dim(`[DEBUG] confirmPlaylistForSending called with: filePath="${filePath}", deviceName="${deviceName}" -> "${actualDeviceName}"`));
     }
     try {
-        // Check if file exists
-        console.log(chalk_1.default.cyan(`Playlist file: ${resolvedPath}`));
-        let _fileExists = false;
+        // Load playlist from file or URL
+        console.log(chalk_1.default.cyan(`Playlist source: ${resolvedPath}`));
         let playlist;
+        let fileExists = false;
+        let loadedFrom = 'file';
         try {
-            const content = await fs_1.promises.readFile(resolvedPath, 'utf-8');
-            playlist = JSON.parse(content);
-            _fileExists = true;
-            console.log(chalk_1.default.green('File loaded'));
+            const loaded = await (0, playlist_source_1.loadPlaylistSource)(resolvedPath);
+            playlist = loaded.playlist;
+            fileExists = loaded.sourceType === 'file';
+            loadedFrom = loaded.sourceType;
+            console.log(chalk_1.default.green(`Loaded from ${loadedFrom}: ${resolvedPath}`));
         }
         catch (error) {
-            const errorMsg = error.message;
-            if (errorMsg.includes('ENOENT') || errorMsg.includes('no such file')) {
-                console.log(chalk_1.default.red(`File not found: ${resolvedPath}`));
+            const message = error.message;
+            const isUrl = (0, playlist_source_1.isPlaylistSourceUrl)(resolvedPath);
+            if (isUrl) {
                 return {
                     success: false,
                     filePath: resolvedPath,
                     fileExists: false,
                     playlistValid: false,
-                    error: `Playlist file not found at ${resolvedPath}`,
-                    message: `Could not find playlist file. Try:\n  • Run a playlist build first\n  • Check the file path is correct\n  • Use "send ./path/to/playlist.json"`,
+                    error: `Could not load playlist URL: ${resolvedPath}`,
+                    message: `${message}\n\nHint:\n  • Check the URL is reachable\n  • Confirm it returns JSON\n  • Use "send ./path/to/playlist.json" for local files`,
                 };
             }
-            throw error;
+            if (message.includes('Invalid JSON in')) {
+                return {
+                    success: false,
+                    filePath: resolvedPath,
+                    fileExists: true,
+                    playlistValid: false,
+                    error: message,
+                    message: `${message}\n\nHint:\n  • Check the JSON payload is valid DP-1 format\n  • Check local path points to a playlist file`,
+                };
+            }
+            return {
+                success: false,
+                filePath: resolvedPath,
+                fileExists: false,
+                playlistValid: false,
+                error: `Playlist file not found at ${resolvedPath}`,
+                message: `Could not find playlist file. Try:\n  • Run a playlist build first\n  • Check the file path is correct\n  • Use "send ./path/to/playlist.json"`,
+            };
         }
         if (!playlist) {
             return {
                 success: false,
                 filePath: resolvedPath,
-                fileExists: true,
+                fileExists,
                 playlistValid: false,
-                error: 'Playlist file is empty',
+                error: `Playlist source is empty: ${loadedFrom}`,
             };
         }
         // Validate playlist structure