@feralfile/cli 1.1.1

package/dist/src/intent-parser/utils.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Intent Parser Utilities
+ * Validation and constraint enforcement for parsed requirements
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyConstraints = applyConstraints;
+const chalk_1 = __importDefault(require("chalk"));
+/**
+ * Apply constraints to parsed requirements
+ *
+ * @param {Object} params - Parsed parameters
+ * @param {Array<Object>} params.requirements - Array of requirements
+ * @param {Object} [params.playlistSettings] - Playlist settings
+ * @param {Object} config - Application config
+ * @returns {Object} Validated parameters
+ */
+function applyConstraints(params, config) {
+    // Validate requirements array
+    if (!params.requirements || !Array.isArray(params.requirements)) {
+        throw new Error('Requirements must be an array');
+    }
+    if (params.requirements.length === 0) {
+        throw new Error('At least one requirement is needed');
+    }
+    // Validate each requirement
+    params.requirements = params.requirements.map((req, index) => {
+        const r = req;
+        if (!r.type) {
+            throw new Error(`Requirement ${index + 1}: type is required`);
+        }
+        // Validate based on type
+        if (r.type === 'build_playlist') {
+            if (!r.blockchain) {
+                throw new Error(`Requirement ${index + 1}: blockchain is required for build_playlist`);
+            }
+            if (!r.contractAddress) {
+                throw new Error(`Requirement ${index + 1}: contractAddress is required for build_playlist`);
+            }
+        }
+        else if (r.type === 'query_address') {
+            if (!r.ownerAddress) {
+                throw new Error(`Requirement ${index + 1}: ownerAddress is required for query_address`);
+            }
+        }
+        else if (r.type === 'fetch_feed') {
+            if (!r.playlistName) {
+                throw new Error(`Requirement ${index + 1}: playlistName is required for fetch_feed`);
+            }
+        }
+        else {
+            throw new Error(`Requirement ${index + 1}: invalid type "${r.type}"`);
+        }
+        // Set default quantity if not provided
+        // Allow "all" as a string value for query_address type
+        let quantity;
+        if (r.quantity === 'all') {
+            quantity = 'all';
+        }
+        else if (r.quantity === null || r.quantity === undefined) {
+            quantity = 5;
+        }
+        else if (typeof r.quantity === 'string') {
+            // Try to parse string numbers
+            const parsed = parseInt(r.quantity, 10);
+            quantity = isNaN(parsed) ? r.quantity : parsed;
+        }
+        else {
+            quantity = r.quantity;
+        }
+        return {
+            ...r,
+            quantity: quantity, // No cap - registry system handles large playlists efficiently
+            tokenIds: r.tokenIds || [],
+        };
+    });
+    // Note: No cap needed - registry system handles large playlists efficiently
+    // Full items are stored in memory, only IDs are sent to AI model
+    const hasAllQuantity = params.requirements.some((r) => r.quantity === 'all');
+    const totalRequested = params.requirements.reduce((sum, r) => {
+        if (typeof r.quantity === 'number') {
+            return sum + r.quantity;
+        }
+        return sum;
+    }, 0);
+    if (hasAllQuantity) {
+        console.log(chalk_1.default.yellow(`\nRequesting all tokens from one or more addresses. This may take a while to fetch and process.\n`));
+    }
+    else if (totalRequested > 100) {
+        console.log(chalk_1.default.yellow(`\nRequesting ${totalRequested} items. This may take a while to fetch and process.\n`));
+    }
+    // Set playlist defaults
+    if (!params.playlistSettings) {
+        params.playlistSettings = {};
+    }
+    // Only set durationPerItem if not already specified
+    if (params.playlistSettings.durationPerItem === undefined) {
+        params.playlistSettings.durationPerItem = config.defaultDuration || 10;
+    }
+    // Only set preserveOrder if not already specified
+    if (params.playlistSettings.preserveOrder === undefined) {
+        params.playlistSettings.preserveOrder = true;
+    }
+    return params;
+}

package/dist/src/logger.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * Simple logging utility that respects verbose mode
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setVerbose = setVerbose;
+exports.debug = debug;
+exports.info = info;
+exports.warn = warn;
+exports.verbose = verbose;
+exports.error = error;
+exports.always = always;
+const chalk_1 = __importDefault(require("chalk"));
+// Global verbose flag
+let isVerbose = false;
+/**
+ * Set verbose mode
+ * @param {boolean} verbose - Whether to enable verbose logging
+ */
+function setVerbose(verbose) {
+    isVerbose = verbose;
+}
+/**
+ * Log debug message (only in verbose mode)
+ * @param {...any} args - Arguments to log
+ */
+function debug(...args) {
+    if (isVerbose) {
+        console.log(chalk_1.default.dim('[DEBUG]'), ...args);
+    }
+}
+/**
+ * Log info message (only in verbose mode)
+ * @param {...any} args - Arguments to log
+ */
+function info(...args) {
+    if (isVerbose) {
+        console.log(chalk_1.default.blue('[INFO]'), ...args);
+    }
+}
+/**
+ * Log warning message (only in verbose mode)
+ * @param {...any} args - Arguments to log
+ */
+function warn(...args) {
+    if (isVerbose) {
+        console.warn(chalk_1.default.yellow('[WARN]'), ...args);
+    }
+}
+/**
+ * Log message only in verbose mode (no prefix)
+ * @param {...any} args - Arguments to log
+ */
+function verbose(...args) {
+    if (isVerbose) {
+        console.log(...args);
+    }
+}
+/**
+ * Log error message (always shown, but with more details in verbose mode)
+ * @param {...any} args - Arguments to log
+ */
+function error(...args) {
+    if (isVerbose) {
+        console.error(chalk_1.default.red('[ERROR]'), ...args);
+    }
+    else {
+        // In non-verbose mode, errors are still shown but handled by the caller
+        // This allows the orchestrator to show clean error messages
+        console.error(chalk_1.default.red('[ERROR]'), ...args);
+    }
+}
+/**
+ * Log message that always shows (bypass verbose mode)
+ * @param {...any} args - Arguments to log
+ */
+function always(...args) {
+    console.log(...args);
+}

package/dist/src/main.js

@@ -0,0 +1,459 @@
+"use strict";
+/**
+ * Main Flow Controller
+ * Handles both deterministic and AI-driven playlist creation
+ */
+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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEND_SHORTCUT_PATTERN = void 0;
+exports.resolveSendShortcutDevice = resolveSendShortcutDevice;
+exports.resolveEffectiveDeviceName = resolveEffectiveDeviceName;
+exports.resolveSendPlaylistDeviceName = resolveSendPlaylistDeviceName;
+exports.validateRequirements = validateRequirements;
+exports.applyPlaylistDefaults = applyPlaylistDefaults;
+exports.buildPlaylistDirect = buildPlaylistDirect;
+exports.buildPlaylist = buildPlaylist;
+// Suppress Ed25519 experimental warning immediately
+const originalEmitWarning = process.emitWarning;
+process.emitWarning = function (warning, type, ctor) {
+    if (((typeof type === 'string' && type === 'ExperimentalWarning') ||
+        (typeof type === 'object' && type?.name === 'ExperimentalWarning')) &&
+        typeof warning === 'string' &&
+        warning.includes('Ed25519')) {
+        return; // Suppress this warning
+    }
+    return originalEmitWarning.apply(this, [warning, type, ctor]);
+};
+const chalk_1 = __importDefault(require("chalk"));
+const readline = __importStar(require("readline"));
+const config_1 = require("./config");
+const logger = __importStar(require("./logger"));
+// Lazy load utilities and orchestrator to avoid circular dependencies
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const getUtilities = () => require('./utilities');
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const getIntentParser = () => require('./intent-parser');
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const getAIOrchestrator = () => require('./ai-orchestrator');
+/**
+ * Regex that matches the inline "send last / send playlist / send to <device>"
+ * shortcut inside the chat flow. Exported for testing.
+ */
+exports.SEND_SHORTCUT_PATTERN = /^send(?:\s+(?:last|playlist|the playlist))?(?:\s+to\s+(.+))?$/i;
+/**
+ * Extract the target device from a sendMatch result, falling back to the CLI
+ * --device flag. Exported for testing.
+ */
+function resolveSendShortcutDevice(match, cliDefault) {
+    return match[1]?.trim() || cliDefault;
+}
+/**
+ * Resolve the effective device name for a send operation.
+ * The intent (from NL parsing) takes precedence; CLI flag is the fallback.
+ * Exported for testing.
+ */
+function resolveEffectiveDeviceName(fromIntent, fromCLI) {
+    return fromIntent || fromCLI;
+}
+/**
+ * Sanitize and resolve the device name for the direct send_playlist action path.
+ *
+ * The intent parser can emit literal "null" or "" as a device name string; these
+ * must be treated as absent so the CLI --device fallback is used instead.
+ * Exported for testing — mirrors the sanitization in confirmPlaylistForSending().
+ */
+function resolveSendPlaylistDeviceName(intentDeviceName, cliDeviceName) {
+    const sanitized = intentDeviceName === 'null' ||
+        intentDeviceName === '' ||
+        intentDeviceName === null ||
+        intentDeviceName === undefined
+        ? undefined
+        : intentDeviceName;
+    return resolveEffectiveDeviceName(sanitized, cliDeviceName);
+}
+/**
+ * Validate and apply constraints to requirements
+ *
+ * @param {Array<Object>} requirements - Array of requirements
+ * @returns {Array<Object>} Validated requirements
+ */
+function validateRequirements(requirements) {
+    if (!requirements || !Array.isArray(requirements) || requirements.length === 0) {
+        throw new Error('At least one requirement is needed');
+    }
+    return requirements.map((req, index) => {
+        // Validate based on requirement type
+        if (req.type === 'fetch_feed') {
+            // Feed playlist requirement - only needs playlistName and quantity
+            if (!req.playlistName) {
+                throw new Error(`Requirement ${index + 1}: playlistName is required for fetch_feed`);
+            }
+            const quantity = typeof req.quantity === 'number' ? Math.min(req.quantity, 20) : 5;
+            return {
+                ...req,
+                quantity,
+            };
+        }
+        // Query address requirement
+        if (req.type === 'query_address') {
+            // Query all NFTs from an owner address
+            if (!req.ownerAddress) {
+                throw new Error(`Requirement ${index + 1}: ownerAddress is required for query_address`);
+            }
+            // Allow "all" as a string, or cap numeric values
+            let quantity;
+            if (req.quantity === 'all') {
+                quantity = 'all';
+            }
+            else if (typeof req.quantity === 'number') {
+                quantity = Math.min(req.quantity, 100);
+            }
+            else {
+                quantity = undefined;
+            }
+            return {
+                ...req,
+                quantity,
+            };
+        }
+        // Build playlist requirement
+        if (req.type === 'build_playlist') {
+            if (!req.blockchain) {
+                throw new Error(`Requirement ${index + 1}: blockchain is required for build_playlist`);
+            }
+            if (!req.contractAddress) {
+                throw new Error(`Requirement ${index + 1}: contractAddress is required for build_playlist`);
+            }
+            // tokenIds is now optional - if not provided, query random tokens from contract
+            if (req.tokenIds && req.tokenIds.length > 0) {
+                // Specific token IDs provided
+                const quantity = typeof req.quantity === 'number'
+                    ? Math.min(req.quantity, 20)
+                    : Math.min(req.tokenIds.length, 20);
+                return {
+                    ...req,
+                    quantity,
+                    tokenIds: req.tokenIds,
+                };
+            }
+            else {
+                // No token IDs - query random tokens from contract
+                const quantity = typeof req.quantity === 'number' ? Math.min(req.quantity, 100) : 100;
+                return {
+                    ...req,
+                    quantity,
+                    tokenIds: undefined, // Explicitly set to undefined
+                };
+            }
+        }
+        throw new Error(`Requirement ${index + 1}: invalid type "${req.type}"`);
+    });
+}
+/**
+ * Apply playlist settings defaults
+ *
+ * @param {Object} settings - Playlist settings
+ * @returns {Object} Settings with defaults
+ */
+function applyPlaylistDefaults(settings = {}) {
+    const config = (0, config_1.getConfig)();
+    return {
+        title: settings.title || null,
+        slug: settings.slug || null,
+        durationPerItem: settings.durationPerItem || config.defaultDuration || 10,
+        preserveOrder: settings.preserveOrder !== false,
+        deviceName: settings.deviceName,
+    };
+}
+/**
+ * Build playlist deterministically from structured parameters
+ * Path 1: Direct execution (no AI)
+ *
+ * @param {Object} params - Playlist parameters
+ * @param {Array<Object>} params.requirements - Array of requirements
+ * @param {Object} [params.playlistSettings] - Playlist settings
+ * @param {Object} options - Options
+ * @param {boolean} [options.verbose=false] - Verbose output
+ * @param {string} [options.outputPath='playlist.json'] - Output path
+ * @returns {Promise<Object>} Result with playlist
+ */
+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);
+}
+/**
+ * Build playlist from natural language request
+ * Path 2: AI-driven execution (intent parser → AI orchestrator → utilities)
+ *
+ * @param {string} userRequest - Natural language request
+ * @param {Object} options - Options
+ * @param {boolean} [options.verbose=false] - Verbose output
+ * @param {string} [options.outputPath='playlist.json'] - Output path
+ * @param {string} [options.modelName] - AI model to use
+ * @param {boolean} [options.interactive=true] - Interactive mode (allow clarification prompts)
+ * @returns {Promise<Object>} Result with playlist
+ */
+async function buildPlaylist(userRequest, options = {}) {
+    const { verbose = false, outputPath = 'playlist.json', modelName, interactive = true, deviceName: defaultDeviceName, } = options;
+    // Enable verbose logging if requested
+    if (verbose) {
+        logger.setVerbose(true);
+    }
+    // Initialize utilities with config (indexer endpoint, API key, etc.)
+    const utilities = getUtilities();
+    const config = (0, config_1.getConfig)();
+    utilities.initializeUtilities(config);
+    try {
+        const trimmedRequest = userRequest.trim();
+        const sendMatch = trimmedRequest.match(/^send(?:\s+(?:last|playlist|the playlist))?(?:\s+to\s+(.+))?$/i);
+        if (sendMatch) {
+            const deviceName = sendMatch[1]?.trim() || defaultDeviceName;
+            const { confirmPlaylistForSending } = await Promise.resolve().then(() => __importStar(require('./utilities/playlist-send')));
+            const confirmation = await confirmPlaylistForSending(outputPath, deviceName);
+            if (!confirmation.success) {
+                if (confirmation.message) {
+                    console.log(chalk_1.default.red(`\n${confirmation.message}`));
+                }
+                return {
+                    success: false,
+                    error: confirmation.error || 'Failed to prepare playlist for sending',
+                    action: 'send_playlist',
+                    playlist: null,
+                };
+            }
+            const sendResult = await utilities.sendToDevice(confirmation.playlist, confirmation.deviceName);
+            if (sendResult.success) {
+                console.log(chalk_1.default.green('\nPlaylist sent'));
+                if (sendResult.deviceName) {
+                    console.log(chalk_1.default.dim(`  Device: ${sendResult.deviceName}`));
+                }
+                console.log();
+                return {
+                    success: true,
+                    playlist: confirmation.playlist,
+                    action: 'send_playlist',
+                };
+            }
+            console.log();
+            console.error(chalk_1.default.red('Send failed'));
+            if (sendResult.error) {
+                console.error(chalk_1.default.red(`  ${sendResult.error}`));
+            }
+            return {
+                success: false,
+                error: sendResult.error || 'Failed to send playlist',
+                playlist: null,
+                action: 'send_playlist',
+            };
+        }
+        // STEP 1: INTENT PARSER
+        // Parse user intent into structured requirements
+        const { processIntentParserRequest } = getIntentParser();
+        let intentParserResult = await processIntentParserRequest(userRequest, {
+            modelName,
+            defaultDeviceName,
+        });
+        // Handle interactive clarification loop
+        while (intentParserResult.needsMoreInfo) {
+            if (!interactive) {
+                // Non-interactive mode: cannot ask for clarification
+                console.error(chalk_1.default.red('\nNeed more information, but running in non-interactive mode. Provide a complete request.'));
+                if (intentParserResult.question) {
+                    console.error(chalk_1.default.yellow('\nQuestion: ') + intentParserResult.question);
+                }
+                process.exit(1);
+            }
+            // Ask user for clarification
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            // Display the AI's question before asking for input
+            if (intentParserResult.question) {
+                console.log(chalk_1.default.cyan('\n') + intentParserResult.question);
+            }
+            const userResponse = await new Promise((resolve) => {
+                rl.question(chalk_1.default.yellow('Your response: '), (answer) => {
+                    rl.close();
+                    resolve(answer.trim());
+                });
+            });
+            if (!userResponse) {
+                console.error(chalk_1.default.red('\nNo response provided. Exiting.'));
+                process.exit(1);
+            }
+            console.log();
+            // Continue intent parser conversation
+            intentParserResult = await processIntentParserRequest(userResponse, {
+                modelName,
+                defaultDeviceName,
+                conversationContext: {
+                    messages: intentParserResult.messages,
+                },
+            });
+        }
+        if (!intentParserResult.approved) {
+            console.error(chalk_1.default.red('\nRequest not approved by intent parser'));
+            return null;
+        }
+        const params = intentParserResult.params;
+        // NOTE: do NOT merge defaultDeviceName into playlistSettings here.
+        // buildPlaylistDirect (src/utilities/index.js) sends whenever
+        // playlistSettings.deviceName is defined, so setting it here would turn
+        // every build-only `chat --device` invocation into an implicit network send.
+        // The CLI --device flag is used only in the two explicit send paths below
+        // (sendMatch shortcut and send_playlist action) via resolveEffectiveDeviceName.
+        // Check if this is a send_playlist action
+        if (params && params.action === 'send_playlist') {
+            // Handle playlist sending directly
+            const sendParams = params;
+            const utilities = getUtilities();
+            console.log();
+            console.log(chalk_1.default.cyan('Sending to device'));
+            const sendResult = await utilities.sendToDevice(sendParams.playlist, resolveSendPlaylistDeviceName(sendParams.deviceName, defaultDeviceName));
+            if (sendResult.success) {
+                console.log(chalk_1.default.green('\nPlaylist sent'));
+                if (sendResult.deviceName) {
+                    console.log(chalk_1.default.dim(`  Device: ${sendResult.deviceName}`));
+                }
+                console.log();
+                return {
+                    success: true,
+                    playlist: sendParams.playlist,
+                    action: 'send_playlist',
+                };
+            }
+            else {
+                // Send failed - return error without showing the playlist summary
+                console.log();
+                console.error(chalk_1.default.red('Send failed'));
+                if (sendResult.error) {
+                    console.error(chalk_1.default.red(`  ${sendResult.error}`));
+                }
+                return {
+                    success: false,
+                    error: sendResult.error || 'Failed to send playlist',
+                    playlist: null,
+                    action: 'send_playlist',
+                };
+            }
+        }
+        // Check if this is a publish_playlist action
+        if (params && params.action === 'publish_playlist') {
+            // Publishing was already handled by intent parser, just return the result
+            const publishParams = params;
+            if (publishParams.success) {
+                return {
+                    success: true,
+                    action: 'publish_playlist',
+                    playlistId: publishParams.playlistId,
+                    feedServer: publishParams.feedServer,
+                };
+            }
+            else {
+                return {
+                    success: false,
+                    error: publishParams.error,
+                    action: 'publish_playlist',
+                };
+            }
+        }
+        // STEP 2: AI ORCHESTRATOR (Function Calling)
+        // AI orchestrates function calls to build playlist
+        const { buildPlaylistWithAI } = getAIOrchestrator();
+        let result = await buildPlaylistWithAI(params, {
+            modelName,
+            verbose,
+            outputPath,
+            interactive,
+            defaultDeviceName,
+        });
+        // Handle confirmation loop in interactive mode
+        while (result.needsConfirmation && interactive) {
+            console.log(chalk_1.default.yellow('\n' + result.question));
+            console.log();
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            const userResponse = await new Promise((resolve) => {
+                rl.question(chalk_1.default.cyan('Your response: '), (answer) => {
+                    rl.close();
+                    resolve(answer.trim());
+                });
+            });
+            if (!userResponse) {
+                console.error(chalk_1.default.red('\nNo response provided. Canceling.'));
+                return null;
+            }
+            console.log();
+            // Continue orchestrator with user's response
+            result = await buildPlaylistWithAI(result.params, {
+                modelName,
+                verbose,
+                outputPath,
+                interactive,
+                defaultDeviceName,
+                conversationContext: {
+                    messages: result.messages,
+                    userResponse,
+                },
+            });
+        }
+        // If no playlist was built, display the AI's message
+        if (!result.playlist && result.message) {
+            console.log(chalk_1.default.yellow('\n' + result.message));
+        }
+        else if (!result.playlist && result.error) {
+            console.error(chalk_1.default.red('\n' + result.error));
+        }
+        return result;
+    }
+    catch (error) {
+        console.error(chalk_1.default.red('\nError:'), error.message);
+        if (verbose) {
+            console.error(chalk_1.default.dim(error.stack));
+        }
+        throw error;
+    }
+}

package/dist/src/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Type definitions for ff-cli
+ */
+Object.defineProperty(exports, "__esModule", { value: true });