@feralfile/cli 1.1.1

package/dist/src/utilities/address-validator.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * Address Validator
+ * Validates Ethereum and Tezos wallet addresses
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateEthereumAddress = validateEthereumAddress;
+exports.validateTezosAddress = validateTezosAddress;
+exports.validateAddresses = validateAddresses;
+const viem_1 = require("viem");
+/**
+ * Validate Ethereum address format
+ * Uses viem library for EIP-55 checksum validation
+ *
+ * @param {string} address - Address to validate
+ * @returns {Object} Validation result
+ * @returns {boolean} returns.valid - Whether address is valid Ethereum format
+ * @returns {string} [returns.error] - Error message if invalid
+ * @returns {string} [returns.normalized] - Checksummed address if valid
+ * @example
+ * const result = validateEthereumAddress('0x1234567890123456789012345678901234567890');
+ * if (result.valid) console.log(result.normalized);
+ */
+function validateEthereumAddress(address) {
+    if (!address || typeof address !== 'string') {
+        return {
+            valid: false,
+            error: 'Address must be a non-empty string',
+        };
+    }
+    try {
+        // viem's isAddress checks format and returns true/false
+        if (!(0, viem_1.isAddress)(address)) {
+            return {
+                valid: false,
+                error: 'Invalid Ethereum address format. Must be 0x followed by 40 hex characters',
+            };
+        }
+        // getAddress returns the checksummed address
+        const normalized = (0, viem_1.getAddress)(address);
+        return {
+            valid: true,
+            normalized,
+        };
+    }
+    catch (err) {
+        return {
+            valid: false,
+            error: `Address validation failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+/**
+ * Validate Tezos address format
+ * Checks tz1, tz2, tz3, and KT1 address prefixes
+ *
+ * @param {string} address - Address to validate
+ * @returns {Object} Validation result
+ * @returns {boolean} returns.valid - Whether address is valid Tezos format
+ * @returns {string} [returns.error] - Error message if invalid
+ * @returns {string} [returns.type] - Address type (user, contract)
+ * @example
+ * const result = validateTezosAddress('tz1VSUr8wwNhLAzempoch5d6hLKEUNvD14');
+ * if (result.valid) console.log(result.type);
+ */
+function validateTezosAddress(address) {
+    if (!address || typeof address !== 'string') {
+        return {
+            valid: false,
+            error: 'Address must be a non-empty string',
+        };
+    }
+    // Tezos addresses use base58 encoding with specific prefixes
+    // tz1, tz2, tz3: user/implicit accounts (34 chars total, or longer with suffix)
+    // KT1: contracts (34 chars total, or longer with suffix)
+    // Base58 alphabet: 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
+    const userAddressRegex = /^tz[1-3][123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{30,}$/;
+    const contractAddressRegex = /^KT1[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{30,}$/;
+    if (userAddressRegex.test(address)) {
+        return {
+            valid: true,
+            type: 'user',
+        };
+    }
+    if (contractAddressRegex.test(address)) {
+        return {
+            valid: true,
+            type: 'contract',
+        };
+    }
+    return {
+        valid: false,
+        error: 'Invalid Tezos address format. Must start with tz1/tz2/tz3 (user) or KT1 (contract)',
+    };
+}
+/**
+ * Validate mixed Ethereum and Tezos addresses, ENS domains, and Tezos domains
+ * Detects address type and applies appropriate validation
+ *
+ * Supported formats:
+ * - Ethereum addresses: 0x followed by 40 hex characters
+ * - Tezos addresses: tz1/tz2/tz3 (user) or KT1 (contract)
+ * - ENS domains: alphanumeric names ending in .eth
+ * - Tezos domains: alphanumeric names ending in .tez
+ *
+ * @param {Array<string>} addresses - Array of addresses to validate
+ * @returns {Object} Validation result
+ * @returns {boolean} returns.valid - Whether all addresses are valid
+ * @returns {Array<Object>} returns.results - Validation result for each address
+ * @returns {Array<string>} returns.errors - List of error messages
+ * @example
+ * const result = validateAddresses(['0x...', 'tz1...', 'reas.eth', 'einstein-rosen.tez']);
+ * if (!result.valid) console.log(result.errors);
+ */
+function validateAddresses(addresses) {
+    const results = [];
+    const errors = [];
+    if (!Array.isArray(addresses)) {
+        errors.push('Input must be an array of addresses');
+        return { valid: false, results, errors };
+    }
+    if (addresses.length === 0) {
+        errors.push('At least one address is required for validation');
+        return { valid: false, results, errors };
+    }
+    for (const address of addresses) {
+        if (typeof address !== 'string') {
+            errors.push(`Invalid input: ${JSON.stringify(address)} is not a string`);
+            results.push({
+                address: String(address),
+                valid: false,
+                type: 'unknown',
+                error: 'Address must be a string',
+            });
+            continue;
+        }
+        const trimmed = address.trim();
+        // Try Ethereum first (starts with 0x)
+        if (trimmed.startsWith('0x')) {
+            const ethResult = validateEthereumAddress(trimmed);
+            if (ethResult.valid) {
+                results.push({
+                    address: trimmed,
+                    valid: true,
+                    type: 'ethereum',
+                    normalized: ethResult.normalized,
+                });
+            }
+            else {
+                const errorMsg = `Invalid Ethereum address "${trimmed}": ${ethResult.error}`;
+                errors.push(errorMsg);
+                results.push({
+                    address: trimmed,
+                    valid: false,
+                    type: 'ethereum',
+                    error: ethResult.error,
+                });
+            }
+        }
+        else if (trimmed.startsWith('tz') || trimmed.startsWith('KT1')) {
+            // Try Tezos
+            const tezResult = validateTezosAddress(trimmed);
+            if (tezResult.valid) {
+                results.push({
+                    address: trimmed,
+                    valid: true,
+                    type: tezResult.type || 'tezos',
+                });
+            }
+            else {
+                const errorMsg = `Invalid Tezos address "${trimmed}": ${tezResult.error}`;
+                errors.push(errorMsg);
+                results.push({
+                    address: trimmed,
+                    valid: false,
+                    type: 'tezos',
+                    error: tezResult.error,
+                });
+            }
+        }
+        else if (trimmed.endsWith('.eth')) {
+            // ENS domain name (Ethereum Name Service)
+            // These are valid owner identifiers that will be resolved to addresses
+            const ensPattern = /^[a-z0-9-]+\.eth$/i;
+            if (ensPattern.test(trimmed)) {
+                results.push({
+                    address: trimmed,
+                    valid: true,
+                    type: 'ens',
+                });
+            }
+            else {
+                const errorMsg = `Invalid ENS domain "${trimmed}". Must be alphanumeric with hyphens ending in .eth`;
+                errors.push(errorMsg);
+                results.push({
+                    address: trimmed,
+                    valid: false,
+                    type: 'ens',
+                    error: 'Invalid ENS domain format',
+                });
+            }
+        }
+        else if (trimmed.endsWith('.tez')) {
+            // Tezos domain name
+            // These are valid owner identifiers that will be resolved to addresses
+            const tezDomainPattern = /^[a-z0-9-]+\.tez$/i;
+            if (tezDomainPattern.test(trimmed)) {
+                results.push({
+                    address: trimmed,
+                    valid: true,
+                    type: 'tezos-domain',
+                });
+            }
+            else {
+                const errorMsg = `Invalid Tezos domain "${trimmed}". Must be alphanumeric with hyphens ending in .tez`;
+                errors.push(errorMsg);
+                results.push({
+                    address: trimmed,
+                    valid: false,
+                    type: 'tezos-domain',
+                    error: 'Invalid Tezos domain format',
+                });
+            }
+        }
+        else {
+            const errorMsg = `Unknown address format "${trimmed}". Must be 0x... (Ethereum), tz/KT1 (Tezos), .eth (ENS), or .tez (Tezos domain)`;
+            errors.push(errorMsg);
+            results.push({
+                address: trimmed,
+                valid: false,
+                type: 'unknown',
+                error: 'Must be Ethereum (0x...), Tezos (tz1/tz2/tz3/KT1), ENS (.eth), or Tezos domain (.tez)',
+            });
+        }
+    }
+    const allValid = results.every((r) => r.valid);
+    return {
+        valid: allValid,
+        results,
+        errors,
+    };
+}

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

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.promoteDeviceToDefault = promoteDeviceToDefault;
+const device_normalize_1 = require("./device-normalize");
+/**
+ * Move the named device to index 0 so it becomes the implicit default.
+ *
+ * Matches by name (case-insensitive) or by host URL, mirroring `device remove`
+ * so unnamed legacy entries can still be targeted.
+ *
+ * @throws {Error} When no device matches the identifier
+ */
+function promoteDeviceToDefault(devices, identifier) {
+    const normalizedArg = identifier.toLowerCase();
+    let normalizedArgHost = '';
+    try {
+        normalizedArgHost = (0, device_normalize_1.normalizeDeviceHost)(identifier).toLowerCase();
+    }
+    catch {
+        // not a valid URL — host matching will not apply
+    }
+    const index = devices.findIndex((d) => (d.name && d.name.toLowerCase() === normalizedArg) ||
+        (d.host && d.host.toLowerCase() === normalizedArg) ||
+        (normalizedArgHost &&
+            d.host &&
+            (0, device_normalize_1.normalizeDeviceHost)(d.host).toLowerCase() === normalizedArgHost));
+    if (index === -1) {
+        throw new Error(`Device "${identifier}" not found`);
+    }
+    const promoted = devices[index];
+    if (index === 0) {
+        return { devices: [...devices], promoted, alreadyDefault: true };
+    }
+    const reordered = [promoted, ...devices.slice(0, index), ...devices.slice(index + 1)];
+    return { devices: reordered, promoted, alreadyDefault: false };
+}

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

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findExistingDeviceEntry = findExistingDeviceEntry;
+/**
+ * Find an existing configured device that corresponds to a newly discovered host.
+ *
+ * Priority (most reliable to least):
+ *  1. mDNS device ID match — the device's stable hardware identity. Checked first
+ *     so a stale row that happens to share the same IP cannot shadow the correct
+ *     entry. Requires the stored entry to have been written with an id field.
+ *  2. Exact URL match — normal case after ID (same host format, no migration).
+ *  3. mDNS hostname component match — both URLs are parsed and only the hostname
+ *     part is compared (same .local name, different underlying IP or port).
+ *  4a. Discovered IP → stored IP: the mDNS discovery reports a resolved IP that
+ *     matches the IP in a stored entry. Bridges .local ↔ stored-IP migration for
+ *     pre-id configs with no stored id.
+ *  4b. New-host IP → stored addresses: the caller provides an IP host (e.g. from
+ *     --host <ip>) and a stored entry has that IP in its addresses list. Bridges
+ *     the reverse direction (.local stored, IP provided by the user).
+ *  5. TXT-name match — if the device advertises a name that matches a stored
+ *     friendly name, treat them as the same device (last-resort fallback for
+ *     configs written before the id field existed).
+ *
+ * Returns the matched entry so callers can preserve the stored friendly name as
+ * the default when prompting, rather than falling back to the raw mDNS label.
+ */
+function findExistingDeviceEntry(existingDevices, newHost, discoveredName, discoveredId, discoveredAddresses) {
+    // 1. mDNS device ID — stable hardware identity, checked before URL so stale
+    //    host entries for other devices at the same IP do not shadow the result.
+    if (discoveredId) {
+        const byId = existingDevices.find((d) => d.id === discoveredId);
+        if (byId) {
+            return byId;
+        }
+    }
+    // 2. Exact URL match
+    const byHost = existingDevices.find((d) => d.host === newHost);
+    if (byHost) {
+        return byHost;
+    }
+    // 3. mDNS hostname component match (ignores port and protocol differences)
+    let newHostname = '';
+    try {
+        newHostname = new URL(newHost).hostname;
+    }
+    catch {
+        // not a valid URL — skip hostname matching
+    }
+    if (newHostname) {
+        const byHostname = existingDevices.find((d) => {
+            try {
+                return new URL(d.host || '').hostname === newHostname;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (byHostname) {
+            return byHostname;
+        }
+    }
+    // Node.js URL.hostname wraps IPv6 addresses in brackets: [fe80::1].
+    // Strip them so comparisons work against the bracket-free strings stored in addresses[].
+    const stripBrackets = (h) => (h.startsWith('[') && h.endsWith(']') ? h.slice(1, -1) : h);
+    // 4a. Discovered IP → stored IP: mDNS reported addresses include the stored entry's IP.
+    //     Skip only when both the stored entry AND the discovered device carry an id that
+    //     differs — in that case the devices are provably distinct. If discoveredId is absent
+    //     (partial avahi result, --host path) allow the address match regardless of whether
+    //     the stored entry has an id; the address is the best identity signal available.
+    if (discoveredAddresses && discoveredAddresses.length > 0) {
+        const byDiscoveredAddress = existingDevices.find((d) => {
+            if (d.id && discoveredId && d.id !== discoveredId) {
+                return false; // different physical devices — do not conflate
+            }
+            try {
+                const storedIp = stripBrackets(new URL(d.host || '').hostname);
+                return discoveredAddresses.includes(storedIp);
+            }
+            catch {
+                return false;
+            }
+        });
+        if (byDiscoveredAddress) {
+            return byDiscoveredAddress;
+        }
+    }
+    // 4b. New-host IP → stored addresses: the new host is an IP URL (IPv4 or IPv6)
+    //     and a stored entry has that IP in its stored addresses list (populated from
+    //     prior mDNS discoveries). This bridges --host <ip/ipv6> → existing .local entry.
+    //     Strip IPv6 brackets before comparing (Node URL.hostname returns '[fe80::1]').
+    const rawHostname = stripBrackets(newHostname);
+    if (rawHostname && (/^[0-9.]+$/.test(rawHostname) || rawHostname.includes(':'))) {
+        const byStoredAddress = existingDevices.find((d) => d.addresses?.includes(rawHostname));
+        if (byStoredAddress) {
+            return byStoredAddress;
+        }
+    }
+    // 5. TXT-name match — only for entries WITHOUT a stored id.
+    //    If a stored entry already has an id and it did not match in step 1, then
+    //    the discovered device is a physically distinct device that merely advertises
+    //    the same friendly name; matching by name alone would resolve to the wrong row
+    //    and cause upsertDevice to overwrite a different device.
+    if (discoveredName) {
+        return existingDevices.find((d) => !d.id && d.name === discoveredName);
+    }
+    return undefined;
+}

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

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeDeviceHost = normalizeDeviceHost;
+exports.normalizeDeviceIdToHost = normalizeDeviceIdToHost;
+/**
+ * Normalize a raw host string into a canonical `http://<host>:<port>` URL.
+ *
+ * Handles:
+ *  - Trailing dot removal (mDNS labels sometimes end with '.')
+ *  - Case-insensitive scheme detection (HTTP://, HTTPS://, http://, https://)
+ *  - Bare IPv6 addresses (e.g. fe80::1 → [fe80::1]) so new URL() can parse them
+ *  - Missing scheme → http://
+ *  - Missing port → 1111
+ */
+function normalizeDeviceHost(host) {
+    let normalized = host.trim().replace(/\.$/, '');
+    if (!normalized) {
+        return normalized;
+    }
+    const lower = normalized.toLowerCase();
+    // Bare IPv6 address (e.g. fe80::1) — must be bracketed before adding http://
+    // so that new URL() doesn't misparse the colons as port separators.
+    // Only applies when there is no existing scheme, no existing brackets, and the
+    // string consists solely of hex digits and colons (the IPv6 character set).
+    if (!lower.startsWith('http://') &&
+        !lower.startsWith('https://') &&
+        !normalized.startsWith('[') &&
+        /^[0-9a-fA-F:]+$/.test(normalized) &&
+        normalized.includes(':')) {
+        normalized = `[${normalized}]`;
+    }
+    if (!lower.startsWith('http://') && !lower.startsWith('https://')) {
+        normalized = `http://${normalized}`;
+    }
+    try {
+        const url = new URL(normalized);
+        const port = url.port || '1111';
+        return `${url.protocol}//${url.hostname}:${port}`;
+    }
+    catch (_error) {
+        return normalized;
+    }
+}
+/**
+ * Resolve a raw device identifier or host string into a canonical host URL.
+ *
+ * Accepts:
+ *  - Full URLs (http://..., HTTPS://...) — forwarded to normalizeDeviceHost
+ *  - IP addresses (contain dots or colons)
+ *  - .local hostnames (contain dots)
+ *  - Raw device IDs (e.g. 'hh9jsnoc', 'FF1-HH9JSNOC', 'ff1-hh9jsnoc') →
+ *    normalized to lowercase and prefixed with 'ff1-' if missing, then '.local' appended
+ */
+function normalizeDeviceIdToHost(rawId) {
+    const lower = rawId.trim().toLowerCase();
+    const looksLikeHost = lower.includes('.') || lower.includes(':') || lower.startsWith('http');
+    if (looksLikeHost) {
+        return normalizeDeviceHost(rawId);
+    }
+    const deviceId = lower.startsWith('ff1-') ? lower : `ff1-${lower}`;
+    return normalizeDeviceHost(`${deviceId}.local`);
+}

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

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.upsertDevice = upsertDevice;
+/**
+ * Strip undefined values from an object so spreads do not overwrite existing
+ * keys with undefined (e.g. when a caller passes id: undefined because the
+ * device was discovered without an ID).
+ */
+function withoutUndefined(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}
+/**
+ * Apply a patch to an entry.
+ *
+ * Addresses are handled specially:
+ *  - Incoming non-empty: replace (fresh discovery data supersedes stale IPs).
+ *  - Host changed, no incoming addresses: clear (stale IPs belonged to the old
+ *    network location; keeping them lets --host <old-ip> match the wrong device
+ *    after DHCP churn or a partial avahi timeout that omits the address field).
+ *  - Same host, no incoming addresses: keep existing (--host path provides no
+ *    addresses; the stored set must be preserved so reverse IP lookup still works).
+ *
+ * Dual-stack accumulation (IPv4 + IPv6) is handled upstream by parseAvahiBrowseOutput
+ * before upsertDevice is called, so the full address set is always present in a single
+ * invocation.
+ */
+function applyPatch(existing, patch) {
+    const hostChanged = patch.host !== undefined && patch.host !== existing.host;
+    let addresses;
+    if (patch.addresses && patch.addresses.length > 0) {
+        addresses = patch.addresses; // fresh data: replace
+    }
+    else if (hostChanged) {
+        addresses = undefined; // host changed, no new IPs: clear stale addresses
+    }
+    else {
+        addresses = existing.addresses; // same host, no new IPs: keep stored set
+    }
+    return { ...existing, ...patch, addresses };
+}
+/**
+ * Insert or update a device in the configured device list.
+ *
+ * Priority:
+ * 0. matchedIndex provided — caller already resolved the row via findExistingDeviceEntry;
+ *    update that position directly. Handles rename + host-change combos where none of
+ *    the id/name/host heuristics below would find the correct row.
+ * 1. Same mDNS device ID → update in-place (preserves position, handles host change).
+ * 2. Same host → update in-place (preserves position and metadata).
+ * 3. Same name, different host → replace in-place (preserves position so that
+ *    devices[0] — the implicit default for play/send/ssh — does not silently change).
+ * 4. Neither match → append.
+ */
+function upsertDevice(existingDevices, newDevice, 
+/** Pre-resolved row index from findExistingDeviceEntry. When provided, the
+ *  heuristics below are skipped and this row is updated directly. */
+matchedIndex) {
+    const devices = [...existingDevices];
+    const patch = withoutUndefined(newDevice);
+    // Case 0: caller already resolved the match — update directly.
+    if (matchedIndex !== undefined && matchedIndex >= 0 && matchedIndex < devices.length) {
+        const isSameHost = devices[matchedIndex].host === newDevice.host;
+        devices[matchedIndex] = applyPatch(devices[matchedIndex], patch);
+        return { devices, updated: isSameHost };
+    }
+    // Case 1: same mDNS device ID — update in-place even when host changed.
+    if (newDevice.id) {
+        const sameIdIndex = devices.findIndex((d) => d.id === newDevice.id);
+        if (sameIdIndex !== -1) {
+            const isSameHost = devices[sameIdIndex].host === newDevice.host;
+            devices[sameIdIndex] = applyPatch(devices[sameIdIndex], patch);
+            return { devices, updated: isSameHost };
+        }
+    }
+    // Case 2: same host — update in-place
+    const sameHostIndex = devices.findIndex((d) => d.host === newDevice.host);
+    if (sameHostIndex !== -1) {
+        devices[sameHostIndex] = applyPatch(devices[sameHostIndex], patch);
+        return { devices, updated: true };
+    }
+    // Case 3: same name, different host — replace in-place to preserve array order.
+    // Spread existing entry first so apiKey/topicID survive a host change.
+    const staleNameIndex = devices.findIndex((d) => d.name === newDevice.name);
+    if (staleNameIndex !== -1) {
+        devices[staleNameIndex] = applyPatch(devices[staleNameIndex], patch);
+        return { devices, updated: false };
+    }
+    // Case 4: new device
+    devices.push({ ...patch });
+    return { devices, updated: false };
+}