@feralfile/cli 1.1.1

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

@@ -0,0 +1,330 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAvahiBrowseOutput = parseAvahiBrowseOutput;
+exports.resolveAvahiResult = resolveAvahiResult;
+exports.discoverFF1Devices = discoverFF1Devices;
+const bonjour_service_1 = require("bonjour-service");
+const child_process_1 = require("child_process");
+const DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * 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 '';
+}
+/**
+ * Parse avahi-browse -t -r output into FF1DiscoveredDevice list.
+ * Handles resolved records (lines starting with '=') with hostname/address/port/txt fields.
+ * Exported for testing.
+ */
+function parseAvahiBrowseOutput(output) {
+    const devices = new Map();
+    const lines = output.split('\n');
+    let current = null;
+    const flushCurrent = () => {
+        if (!current?.rawHost) {
+            return;
+        }
+        const host = normalizeMdnsHost(current.rawHost).toLowerCase();
+        const key = `${host}:${current.port ?? 1111}`;
+        const id = getHostnameId(host) || current.id;
+        const newAddresses = current.rawAddresses ?? [];
+        // Merge with an existing entry for the same key (e.g. IPv4 + IPv6 records
+        // for the same .local hostname both resolve to the same host:port key).
+        // Prefer TXT-sourced metadata from whichever record has it; a later partial
+        // record must not clobber a previously complete name/id/txt.
+        const existing = devices.get(key);
+        const mergedAddresses = [...(existing?.addresses ?? []), ...newAddresses].filter((addr, i, arr) => arr.indexOf(addr) === i); // deduplicate
+        // Select the richer txt: ignore empty objects (avahi emits txt=[] → {}) so a
+        // partial record with no real TXT data does not block a later complete payload.
+        const existingTxtContent = existing?.txt && Object.keys(existing.txt).length > 0 ? existing.txt : undefined;
+        const currentTxtContent = current.txt && Object.keys(current.txt).length > 0 ? current.txt : undefined;
+        // Prefer whichever txt is non-empty; if both are non-empty, keep the first seen.
+        const mergedTxt = existingTxtContent ?? currentTxtContent;
+        // For name: prefer TXT-sourced name from whichever record has content.
+        const mergedName = existingTxtContent?.name ||
+            currentTxtContent?.name ||
+            existing?.name ||
+            current.name ||
+            id ||
+            host;
+        // For id: prefer existing id (already validated) over newly derived id.
+        const mergedId = existing?.id || id;
+        devices.set(key, {
+            name: mergedName,
+            host,
+            port: current.port ?? 1111,
+            id: mergedId,
+            txt: mergedTxt,
+            addresses: mergedAddresses.length > 0 ? mergedAddresses : undefined,
+        });
+    };
+    for (const line of lines) {
+        // Resolved record header: "=  wlan0 IPv4 FF1-HH9JSNOC   _ff1._tcp   local"
+        if (/^=\s/.test(line)) {
+            flushCurrent();
+            const parts = line.trim().split(/\s+/);
+            // parts: ['=', 'wlan0', 'IPv4', 'My Device Name', '_ff1._tcp', 'local']
+            // Service name may be multi-word; find the type token to bound the slice.
+            // Use a prefix regex so "_ff1._tcp.local" and "_ff1._tcp" both match.
+            // Preserve original case — resolveConfiguredDevice does exact-match lookups.
+            const typeIndex = parts.findIndex((p) => /^_ff1\._tcp/.test(p));
+            const serviceName = typeIndex > 3 ? parts.slice(3, typeIndex).join(' ') : parts[3] || '';
+            current = { name: serviceName };
+            continue;
+        }
+        if (!current) {
+            continue;
+        }
+        const hostnameMatch = line.match(/^\s+hostname\s*=\s*\[(.+)\]/);
+        if (hostnameMatch) {
+            current.rawHost = hostnameMatch[1];
+            continue;
+        }
+        const addressMatch = line.match(/^\s+address\s*=\s*\[(.+)\]/);
+        if (addressMatch) {
+            if (!current.rawAddresses) {
+                current.rawAddresses = [];
+            }
+            current.rawAddresses.push(addressMatch[1].trim());
+            continue;
+        }
+        const portMatch = line.match(/^\s+port\s*=\s*\[(\d+)\]/);
+        if (portMatch) {
+            current.port = parseInt(portMatch[1], 10);
+            continue;
+        }
+        const txtMatch = line.match(/^\s+txt\s*=\s*\[(.+)\]/);
+        if (txtMatch) {
+            const txt = {};
+            const pairs = txtMatch[1].matchAll(/"([^=]+)=([^"]*)"/g);
+            for (const [, k, v] of pairs) {
+                txt[k] = v;
+            }
+            current.txt = txt;
+            if (txt.name) {
+                current.name = txt.name;
+            }
+            if (txt.id) {
+                current.id = txt.id;
+            }
+            continue;
+        }
+    }
+    // Flush last record
+    flushCurrent();
+    return Array.from(devices.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Resolve the result of an avahi-browse subprocess call into an FF1DiscoveryResult
+ * or null (which triggers the Bonjour fallback).
+ *
+ * Rules:
+ *  - Clean exit (error === null): parse stdout and return whatever was found.
+ *  - Non-zero exit + usable stdout: avahi-browse can be killed by the execFile
+ *    timeout after emitting fully resolved records. Use the parsed devices if
+ *    ≥1 was found; otherwise return empty result (avahi is present but slow —
+ *    do NOT fall back to Bonjour, which is less reliable on Linux).
+ *  - Timeout (error.killed === true) + no usable stdout: avahi is present but
+ *    the scan produced nothing before the deadline. Return empty rather than
+ *    falling back to Bonjour.
+ *  - Command not found (ENOENT): avahi-browse is not installed — return null
+ *    so the caller falls back to Bonjour.
+ *  - Other error + no usable stdout: treat as unavailable — null.
+ *
+ * Exported for unit testing.
+ */
+function resolveAvahiResult(error, stdout) {
+    if (error) {
+        if (stdout) {
+            try {
+                const devices = parseAvahiBrowseOutput(stdout);
+                if (devices.length > 0) {
+                    return { devices };
+                }
+            }
+            catch {
+                // unparseable output — fall through
+            }
+        }
+        // Timeout: avahi is present but the scan was slow. Return empty rather than
+        // falling back to Bonjour, which is unreliable on Linux.
+        if (error.killed) {
+            return { devices: [], error: 'avahi-browse timed out before finding any devices' };
+        }
+        // ENOENT: avahi-browse not installed — fall back to Bonjour.
+        // All other errors with no usable output: also fall back.
+        return null;
+    }
+    try {
+        return { devices: parseAvahiBrowseOutput(stdout) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Discover FF1 devices using avahi-browse (Linux).
+ * Returns null if avahi-browse is not available.
+ */
+function discoverViaAvahi(options) {
+    return new Promise((resolve) => {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        (0, child_process_1.execFile)('avahi-browse', ['-t', '-r', '_ff1._tcp'], { timeout: timeoutMs }, (error, stdout, _stderr) => {
+            resolve(resolveAvahiResult(error, stdout));
+        });
+    });
+}
+/**
+ * Discover FF1 devices via mDNS using the `_ff1._tcp` service.
+ * On Linux, uses avahi-browse for reliable multi-device discovery.
+ * Falls back to bonjour-service on other platforms or if avahi is unavailable.
+ *
+ * @param {Object} [options] - Discovery options
+ * @param {number} [options.timeoutMs] - How long to browse before returning results (bonjour fallback only)
+ * @returns {Promise<FF1DiscoveryResult>} Discovered FF1 devices and optional error
+ * @throws {Error} Never throws; returns empty list on errors
+ * @example
+ * const result = await discoverFF1Devices();
+ */
+async function discoverFF1Devices(options = {}, 
+// Injectable for testing — callers should omit these; defaults use the real implementations.
+_avahiDiscovery = discoverViaAvahi, _bonjourDiscovery = discoverViaBonjour) {
+    if (process.platform === 'linux') {
+        const avahiResult = await _avahiDiscovery(options);
+        if (avahiResult !== null) {
+            return avahiResult;
+        }
+    }
+    return _bonjourDiscovery(options);
+}
+function discoverViaBonjour(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}`;
+                const addresses = Array.isArray(service.addresses) && service.addresses.length > 0
+                    ? service.addresses
+                    : undefined;
+                devices.set(key, {
+                    name,
+                    host,
+                    port,
+                    id,
+                    fqdn: service.fqdn,
+                    txt,
+                    addresses,
+                });
+            });
+            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

@@ -0,0 +1,308 @@
+/**
+ * Function Calling Layer
+ * These are the actual implementations called by AI orchestrator via function calling
+ */
+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;
+    };
+})();
+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
+ *
+ * This is the actual implementation called by AI orchestrator's function calling.
+ * Uses core playlist-builder utilities.
+ *
+ * @param {Object} params - Build parameters
+ * @param {Array<Object>} params.items - Playlist items
+ * @param {string} [params.title] - Playlist title (auto-generated if not provided)
+ * @param {string} [params.slug] - Playlist slug (auto-generated if not provided)
+ * @returns {Promise<Object>} DP1 playlist
+ * @example
+ * const playlist = await buildDP1Playlist({ items, title: 'My Playlist' });
+ */
+async function buildDP1Playlist(params) {
+    const { items, title, slug } = params;
+    return await playlistBuilder.buildDP1Playlist({ items, title, slug });
+}
+/**
+ * Send playlist to FF1 device
+ *
+ * This is the actual implementation called by AI orchestrator's function calling.
+ *
+ * @param {Object} params - Send parameters
+ * @param {Object} params.playlist - DP1 playlist
+ * @param {string} [params.deviceName] - Device name (null for first device)
+ * @returns {Promise<Object>} Result
+ * @returns {boolean} returns.success - Whether send succeeded
+ * @returns {string} [returns.deviceHost] - Device host address
+ * @returns {string} [returns.deviceName] - Device name
+ * @returns {string} [returns.error] - Error message if failed
+ * @example
+ * const result = await sendPlaylistToDevice({ playlist, deviceName: 'MyDevice' });
+ */
+async function sendPlaylistToDevice(params) {
+    const { playlist, deviceName } = params;
+    const result = await ff1Device.sendPlaylistToDevice({
+        playlist,
+        deviceName,
+    });
+    if (result.success) {
+        console.log(chalk.green('\nSent to device'));
+        if (result.deviceName) {
+            console.log(chalk.dim(`  ${result.deviceName}`));
+        }
+    }
+    else {
+        console.error(chalk.red('\nSend failed'));
+        if (result.error) {
+            console.error(chalk.red(`  ${result.error}`));
+        }
+    }
+    return result;
+}
+/**
+ * Resolve blockchain domain names to addresses
+ *
+ * This is the actual implementation called by AI orchestrator's function calling.
+ * Supports ENS (.eth) and TNS (.tez) domains with batch resolution.
+ *
+ * @param {Object} params - Resolution parameters
+ * @param {Array<string>} params.domains - Array of domain names to resolve
+ * @param {boolean} [params.displayResults] - Whether to display results (default: true)
+ * @returns {Promise<Object>} Resolution result
+ * @returns {boolean} returns.success - Whether at least one domain was resolved
+ * @returns {Object} returns.domainMap - Map of domain to resolved address
+ * @returns {Array<Object>} returns.resolutions - Detailed resolution results
+ * @returns {Array<string>} returns.errors - Array of error messages
+ * @example
+ * const result = await resolveDomains({ domains: ['vitalik.eth', 'alice.tez'] });
+ * console.log(result.domainMap); // { 'vitalik.eth': '0x...', 'alice.tez': 'tz...' }
+ */
+async function resolveDomains(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}`));
+        return {
+            success: false,
+            domainMap: {},
+            resolutions: [],
+            errors: [error],
+        };
+    }
+    const result = await domainResolver.resolveDomainsBatch(domains);
+    if (displayResults) {
+        domainResolver.displayResolutionResults(result);
+    }
+    return result;
+}
+/**
+ * Verify a playlist against DP-1 specification
+ *
+ * This is the actual implementation called by AI orchestrator's function calling.
+ * Uses dp1-js parse/structure validation (same as the `validate` CLI). Does not
+ * verify signatures; use the `verify` CLI for cryptographic checks. Must be
+ * called before sending a playlist to a device from the orchestrator.
+ *
+ * @param {Object} params - Verification parameters
+ * @param {Object} params.playlist - Playlist object to verify
+ * @returns {Promise<Object>} Verification result
+ * @returns {boolean} returns.valid - Whether playlist is valid
+ * @returns {string} [returns.error] - Error message if invalid
+ * @returns {Array<Object>} [returns.details] - Detailed validation errors
+ * @example
+ * const result = await verifyPlaylist({ playlist });
+ * if (result.valid) {
+ *   console.log('Playlist is valid');
+ * } else {
+ *   console.error('Invalid:', result.error);
+ * }
+ */
+async function verifyPlaylist(params) {
+    const { playlist } = params;
+    if (!playlist) {
+        return {
+            valid: false,
+            error: 'No playlist provided for verification',
+        };
+    }
+    logger.verbose(chalk.cyan('\nValidate playlist'));
+    // Dynamic import to avoid circular dependency
+    const playlistVerifier = await Promise.resolve().then(() => __importStar(require('./playlist-verifier')));
+    const validate = playlistVerifier.validatePlaylist ||
+        (playlistVerifier.default && playlistVerifier.default.validatePlaylist) ||
+        playlistVerifier.default;
+    if (typeof validate !== 'function') {
+        return {
+            valid: false,
+            error: 'Playlist verifier is not available',
+        };
+    }
+    const result = await validate(playlist);
+    if (result.valid) {
+        logger.verbose(chalk.green('Playlist looks good'));
+        if (playlist.title) {
+            logger.verbose(chalk.dim(`  Title: ${playlist.title}`));
+        }
+        if (playlist.items) {
+            logger.verbose(chalk.dim(`  Items: ${playlist.items.length}`));
+        }
+        logger.verbose();
+    }
+    else {
+        console.error(chalk.red('Playlist has issues'));
+        console.error(chalk.red(`  ${result.error}`));
+        if (result.details && result.details.length > 0) {
+            console.log(chalk.yellow('\n  Missing or invalid fields:'));
+            result.details.forEach((detail) => {
+                console.log(chalk.yellow(`    • ${detail.path}: ${detail.message}`));
+            });
+        }
+        console.log();
+    }
+    return result;
+}
+/**
+ * Verify and validate Ethereum and Tezos addresses
+ *
+ * This function is called by the intent parser to validate addresses entered by users.
+ * It provides detailed feedback on address validity and format issues.
+ *
+ * @param {Object} params - Verification parameters
+ * @param {Array<string>} params.addresses - Array of addresses to verify
+ * @returns {Promise<Object>} Verification result
+ * @returns {boolean} returns.valid - Whether all addresses are valid
+ * @returns {Array<Object>} returns.results - Detailed validation for each address
+ * @returns {Array<string>} returns.errors - List of validation errors
+ * @example
+ * const result = await verifyAddresses({
+ *   addresses: ['0x1234567890123456789012345678901234567890', 'tz1VSUr8wwNhLAzempoch5d6hLKEUNvD14']
+ * });
+ * if (!result.valid) {
+ *   result.errors.forEach(err => console.error(err));
+ * }
+ */
+async function verifyAddresses(params) {
+    const { addresses } = params;
+    if (!addresses || !Array.isArray(addresses) || addresses.length === 0) {
+        return {
+            valid: false,
+            results: [],
+            errors: ['No addresses provided for verification'],
+        };
+    }
+    // Dynamic import to avoid circular dependency
+    const addressValidator = await Promise.resolve().then(() => __importStar(require('./address-validator')));
+    const validateAddresses = addressValidator.validateAddresses ||
+        (addressValidator.default && addressValidator.default.validateAddresses) ||
+        addressValidator.default;
+    if (typeof validateAddresses !== 'function') {
+        return {
+            valid: false,
+            results: [],
+            errors: ['Address validator is not available'],
+        };
+    }
+    const result = validateAddresses(addresses);
+    // Display results
+    if (!result.valid) {
+        console.error(chalk.red('\nAddress validation failed'));
+        result.errors.forEach((err) => {
+            console.error(chalk.red(`  • ${err}`));
+        });
+        console.log();
+    }
+    return result;
+}
+/**
+ * Get list of configured FF1 devices
+ *
+ * This function retrieves the list of all configured FF1 devices from config.
+ * Called by intent parser to resolve generic device references like "FF1", "my device".
+ *
+ * @returns {Promise<Object>} Device list result
+ * @returns {boolean} returns.success - Whether devices were retrieved
+ * @returns {Array<Object>} returns.devices - Array of device configurations
+ * @returns {string} returns.devices[].name - Device name
+ * @returns {string} returns.devices[].host - Device host URL
+ * @returns {string} [returns.devices[].topicID] - Optional topic ID
+ * @returns {string} [returns.error] - Error message if no devices configured
+ * @example
+ * const result = await getConfiguredDevices();
+ * if (result.success && result.devices.length > 0) {
+ *   const firstDevice = result.devices[0].name;
+ * }
+ */
+async function getConfiguredDevices() {
+    const configModule = await Promise.resolve().then(() => __importStar(require('../config')));
+    const getFF1DeviceConfig = configModule.getFF1DeviceConfig ||
+        (configModule.default && configModule.default.getFF1DeviceConfig) ||
+        configModule.default;
+    if (typeof getFF1DeviceConfig !== 'function') {
+        return {
+            success: false,
+            devices: [],
+            error: 'FF1 device configuration is not available',
+        };
+    }
+    const deviceConfig = getFF1DeviceConfig();
+    if (!deviceConfig.devices || deviceConfig.devices.length === 0) {
+        return {
+            success: false,
+            devices: [],
+            error: 'No FF1 devices configured',
+        };
+    }
+    // Return sanitized device list (without API keys)
+    const devices = deviceConfig.devices.map((d) => ({
+        name: d.name || d.host,
+        host: d.host,
+        topicID: d.topicID,
+    }));
+    return {
+        success: true,
+        devices,
+    };
+}
+module.exports = {
+    buildDP1Playlist,
+    sendPlaylistToDevice,
+    resolveDomains,
+    verifyPlaylist,
+    getConfiguredDevices,
+    verifyAddresses,
+};