@ciphore/radiocli 0.2.2 → 0.2.4

package/dist/storage/store.js

@@ -1,3 +1,5 @@
+import { platformPaths } from '../platform/paths.js';
+import { assertStorageWritable } from '../platform/storage.js';
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
@@ -5,7 +7,6 @@ import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { defaultReceiverStyle, receiverStyleNames, themeNames } from '../types.js';
 import { canonicalizeAlarmTime, canonicalizeIsoWeekdays, canonicalizeTimeZone } from '../alarms/schedule.js';
-import { backupBadFile } from '../providers/cache.js';
 import { migrateReceiverStyle } from '../ui/visualizers/receiver-style-registry.js';
 const stationSchema = z
     .object({
@@ -61,7 +62,25 @@ const settingsSchema = z.object({
     transparentBackground: z.boolean().default(false),
     asciiMode: z.boolean().default(false),
     reduceMotion: z.boolean().default(false),
-    mouseSupport: z.boolean().default(true)
+    mouseSupport: z.boolean().default(true),
+    automaticUpdateChecks: z.boolean().default(true),
+    agentControl: z.object({
+        enabled: z.boolean().default(false),
+        openUiOnPlay: z.boolean().default(true),
+        focusNowPlaying: z.boolean().default(true),
+        completionPreset: z.object({
+            action: z.enum(['play', 'pause', 'resume', 'stop']).default('play'),
+            source: z.enum(['recent', 'favorite', 'popular', 'country']).default('recent'),
+            countryCode: z.string().length(2).optional(),
+            ifPlaying: z.enum(['keep', 'replace']).default('keep'),
+            openUi: z.boolean().optional()
+        }).default({ action: 'play', source: 'recent', ifPlaying: 'keep' })
+    }).default({
+        enabled: false,
+        openUiOnPlay: true,
+        focusNowPlaying: true,
+        completionPreset: { action: 'play', source: 'recent', ifPlaying: 'keep' }
+    })
 });
 const absoluteInstantSchema = z.string().refine(value => /(?:Z|[+-]\d{2}:\d{2})$/.test(value) && Number.isFinite(Date.parse(value)), { message: 'Expected an absolute ISO-8601 instant with a timezone offset.' });
 const alarmMinuteInstantSchema = absoluteInstantSchema.refine(value => new Date(value).getUTCSeconds() === 0 && new Date(value).getUTCMilliseconds() === 0, { message: 'Alarm occurrences use minute precision; seconds must be zero.' });
@@ -194,6 +213,13 @@ const librarySchema = z.object({
         tuneTimeoutSeconds: 12,
         skipBrokenStreams: true,
         mouseSupport: true,
+        automaticUpdateChecks: true,
+        agentControl: {
+            enabled: false,
+            openUiOnPlay: true,
+            focusNowPlaying: true,
+            completionPreset: { action: 'play', source: 'recent', ifPlaying: 'keep' }
+        },
         mediaKeys: defaultMediaKeys
     })
 });
@@ -209,7 +235,7 @@ export class JsonLibraryStore {
     state;
     idGenerator;
     now;
-    constructor(filePath = defaultStorePath(), options = {}) {
+    constructor(filePath = defaultLibraryPath(), options = {}) {
         this.filePath = filePath;
         this.idGenerator = options.idGenerator ?? randomUUID;
         this.now = options.now ?? (() => new Date());
@@ -471,13 +497,21 @@ export class JsonLibraryStore {
         return this.commit({ ...this.state, favorites });
     }
     addImported(stations) {
-        const existing = new Map(this.state.imported.map(station => [stationKey(station), station]));
+        const incoming = [];
+        const incomingKeys = new Set();
         for (const station of stations) {
-            existing.set(stationKey(station), station);
+            const key = stationKey(station);
+            if (incomingKeys.has(key))
+                continue;
+            incomingKeys.add(key);
+            incoming.push(station);
         }
         return this.commit({
             ...this.state,
-            imported: [...existing.values()].slice(0, 1000)
+            imported: [
+                ...incoming,
+                ...this.state.imported.filter(station => !incomingKeys.has(stationKey(station)))
+            ].slice(0, 1000)
         });
     }
     isFavorite(station) {
@@ -510,14 +544,27 @@ export class JsonLibraryStore {
         }
     }
     read() {
-        if (!existsSync(this.filePath)) {
-            return defaultState();
+        let contents;
+        try {
+            contents = readFileSync(this.filePath, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return defaultState();
+            throw storageError('read the RadioCLI library', error);
         }
         try {
-            return migrateLibraryState(librarySchema.parse(JSON.parse(readFileSync(this.filePath, 'utf8'))));
+            return migrateLibraryState(librarySchema.parse(JSON.parse(contents)));
         }
         catch {
-            backupBadFile(this.filePath);
+            try {
+                assertStorageWritable(this.filePath);
+                renameSync(this.filePath, `${this.filePath}.bad-${Date.now()}-${randomUUID()}`);
+            }
+            catch (error) {
+                // Reset only after preserving the original bytes. A failed read never reaches here.
+                throw storageError('preserve the corrupt RadioCLI library', error);
+            }
             return defaultState();
         }
     }
@@ -535,8 +582,14 @@ export class JsonLibraryStore {
         }
     }
     write(state) {
-        mkdirSync(dirname(this.filePath), { recursive: true, mode: 0o700 });
-        writeJsonAtomically(this.filePath, libraryStateForDisk(state));
+        try {
+            assertStorageWritable(this.filePath);
+            mkdirSync(dirname(this.filePath), { recursive: true, mode: 0o700 });
+            writeJsonAtomically(this.filePath, libraryStateForDisk(state));
+        }
+        catch (error) {
+            throw storageError('write the RadioCLI library', error);
+        }
     }
 }
 export function stationKey(station) {
@@ -577,31 +630,21 @@ function recoverActiveListeningSessionInState(state) {
             : Date.now();
     return finishActiveListeningSessionInState(state, new Date(recoveredEnd));
 }
-function defaultStorePath() {
-    if (process.env.RADIOCLI_HOME) {
-        return join(process.env.RADIOCLI_HOME, 'radiocli.json');
-    }
-    if (process.env.RADIO_ATLAS_HOME) {
-        return join(process.env.RADIO_ATLAS_HOME, 'radio-atlas.json');
-    }
-    const currentPath = currentDefaultStorePath();
-    const legacyPath = legacyDefaultStorePath();
-    return existsSync(currentPath) || !existsSync(legacyPath) ? currentPath : legacyPath;
-}
-function currentDefaultStorePath() {
-    if (process.platform === 'darwin') {
-        return join(homedir(), 'Library', 'Application Support', 'radiocli', 'radiocli.json');
-    }
-    if (process.platform === 'win32') {
-        return join(process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming'), 'RadioCLI', 'radiocli.json');
-    }
-    return join(process.env.XDG_DATA_HOME ?? join(homedir(), '.local', 'share'), 'radiocli', 'radiocli.json');
-}
-function legacyDefaultStorePath() {
-    if (process.platform === 'darwin') {
-        return join(homedir(), 'Library', 'Application Support', 'radio-atlas', 'radio-atlas.json');
+export function defaultLibraryPath() {
+    const { library, legacyLibrary } = platformPaths();
+    for (const filePath of [library, legacyLibrary]) {
+        try {
+            statSync(filePath);
+            return filePath;
+        }
+        catch (error) {
+            // A permission failure must not select an older library or empty defaults.
+            if (error.code !== 'ENOENT') {
+                throw storageError('read the RadioCLI library', error);
+            }
+        }
     }
-    return join(process.env.XDG_DATA_HOME ?? join(homedir(), '.local', 'share'), 'radio-atlas', 'radio-atlas.json');
+    return library;
 }
 function resolveUserPath(requestedPath) {
     const unquoted = requestedPath.trim().replace(/^(?:"([\s\S]*)"|'([\s\S]*)')$/, (_match, doubleQuoted, singleQuoted) => doubleQuoted ?? singleQuoted ?? '');
@@ -636,6 +679,13 @@ function defaultState() {
             tuneTimeoutSeconds: 12,
             skipBrokenStreams: true,
             mouseSupport: true,
+            automaticUpdateChecks: true,
+            agentControl: {
+                enabled: false,
+                openUiOnPlay: true,
+                focusNowPlaying: true,
+                completionPreset: { action: 'play', source: 'recent', ifPlaying: 'keep' }
+            },
             mediaKeys: defaultMediaKeys
         }
     };
@@ -668,53 +718,87 @@ function libraryStateForDisk(state) {
         : state;
 }
 function writeJsonAtomically(filePath, value) {
-    const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    const tempPath = `${filePath}.tmp-${process.pid}-${randomUUID()}`;
     try {
-        writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
-        renameSync(tempPath, filePath);
+        writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
         if (process.platform !== 'win32') {
-            chmodSync(filePath, 0o600);
+            chmodSync(tempPath, 0o600);
         }
+        // No fallible persistence steps follow the atomic replacement.
+        renameSync(tempPath, filePath);
     }
     catch (error) {
-        rmSync(tempPath, { force: true });
-        throw error;
+        try {
+            rmSync(tempPath, { force: true });
+        }
+        catch { /* Preserve the original write failure. */ }
+        throw storageError('write RadioCLI data', error);
     }
 }
 function acquireStoreLock(filePath) {
     const lockPath = `${filePath}.lock`;
-    mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+    try {
+        assertStorageWritable(filePath);
+        mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+    }
+    catch (error) {
+        throw storageError('write the RadioCLI library', error);
+    }
     const deadline = Date.now() + 1000;
     while (true) {
         try {
             mkdirSync(lockPath, { mode: 0o700 });
-            return () => rmSync(lockPath, { recursive: true, force: true });
+            return () => {
+                // The write has already succeeded or failed. Lock cleanup cannot reverse that result.
+                try {
+                    rmSync(lockPath, { recursive: true, force: true });
+                }
+                catch { /* Stale locks expire below. */ }
+            };
         }
         catch (error) {
             const code = error.code;
             if (code !== 'EEXIST')
-                throw error;
+                throw storageError('lock the RadioCLI library', error);
             try {
                 if (Date.now() - statSync(lockPath).mtimeMs > 10_000) {
                     rmSync(lockPath, { recursive: true, force: true });
-                    continue;
                 }
             }
-            catch {
-                continue;
+            catch (lockError) {
+                if (lockError.code !== 'ENOENT') {
+                    throw storageError('lock the RadioCLI library', lockError);
+                }
             }
             if (Date.now() >= deadline) {
-                throw new Error(`RadioCLI library is busy: ${filePath}`);
+                throw storageError('lock the RadioCLI library', Object.assign(new Error('Another writer holds the library lock.'), { code: 'EBUSY', cause: error }));
             }
             Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
         }
     }
 }
+class LibraryStorageError extends Error {
+    code;
+    errno;
+    constructor(operation, cause) {
+        const code = cause?.code;
+        const detail = typeof code === 'string' && /^[A-Z][A-Z0-9_]+$/.test(code) ? ` (${code})` : '';
+        super(code === 'EBUSY'
+            ? 'The RadioCLI library is busy. Retry after the other writer finishes, or set RADIOCLI_HOME to a private writable directory.'
+            : `Unable to ${operation}${detail}. Check storage permissions or set RADIOCLI_HOME to a private writable directory.`, { cause });
+        this.name = 'LibraryStorageError';
+        this.code = code;
+        this.errno = cause?.errno;
+    }
+}
+function storageError(operation, cause) {
+    return cause instanceof LibraryStorageError ? cause : new LibraryStorageError(operation, cause);
+}
 function mergeLibraryChanges(base, disk, next) {
     return {
         recent: mergeKeyedChanges(base.recent, disk.recent, next.recent, item => stationKey(item.station), 50),
         favorites: mergeKeyedChanges(base.favorites, disk.favorites, next.favorites, stationKey, 200, true),
-        imported: mergeKeyedChanges(base.imported, disk.imported, next.imported, stationKey, 1000, true),
+        imported: mergeKeyedChanges(base.imported, disk.imported, next.imported, stationKey, 1000, true, true),
         trackHistory: mergeKeyedChanges(base.trackHistory, disk.trackHistory, next.trackHistory, item => `${item.at}:${item.stationKey}:${item.title}`, 100),
         searchHistory: mergeSearchHistory(base.searchHistory, disk.searchHistory, next.searchHistory),
         alarms: mergeKeyedChanges(base.alarms, disk.alarms, next.alarms, alarm => alarm.id, MAX_ALARMS, true),
@@ -736,15 +820,16 @@ function normalizeAlarm(alarm) {
         };
     return { ...alarm, schedule };
 }
-function mergeKeyedChanges(base, disk, next, keyFor, limit, applyRemovals = false) {
+function mergeKeyedChanges(base, disk, next, keyFor, limit, applyRemovals = false, applyOrderChanges = false) {
     const baseByKey = new Map(base.map(item => [keyFor(item), item]));
+    const basePositions = new Map(base.map((item, index) => [keyFor(item), index]));
     const nextKeys = new Set(next.map(keyFor));
     const removedKeys = applyRemovals
         ? new Set(base.map(keyFor).filter(key => !nextKeys.has(key)))
         : new Set();
-    const localChanges = next.filter(item => {
+    const localChanges = next.filter((item, index) => {
         const prior = baseByKey.get(keyFor(item));
-        return prior === undefined || !sameValue(prior, item);
+        return prior === undefined || !sameValue(prior, item) || applyOrderChanges && basePositions.get(keyFor(item)) !== index;
     });
     const changedKeys = new Set(localChanges.map(keyFor));
     return [

package/dist/streams/import-stream.js

@@ -0,0 +1,163 @@
+import { withExternalResponse } from '../platform/network.js';
+import { safeExternalHttpUrl, sanitizeTerminalText } from '../safety.js';
+import { stationFromUrl } from '../playlists/playlist.js';
+class DefiniteStreamError extends Error {
+}
+/**
+ * Build a custom station and enrich it from bounded HTTP/ICY response headers.
+ * The submitted URL is intentionally retained because a followed redirect may
+ * contain a short-lived playback token.
+ */
+export async function importStreamUrl(input, requestedName, options = {}) {
+    const url = validatedStreamUrl(input);
+    const explicitName = sanitizeTerminalText(requestedName);
+    try {
+        let metadata = await probeStreamHeaders(url, options);
+        const listing = await probeIHeartListing(url, options).catch(() => undefined);
+        if (listing)
+            metadata = { ...metadata, ...listing };
+        const name = explicitName ?? metadata.name ?? fallbackStationName(url);
+        return {
+            station: {
+                ...stationFromUrl(url, name),
+                ...(metadata.homepage ? { homepage: metadata.homepage } : {}),
+                ...(metadata.codec ? { codec: metadata.codec } : {}),
+                ...(metadata.bitrate ? { bitrate: metadata.bitrate } : {}),
+                ...(metadata.hls !== undefined ? { hls: metadata.hls } : {})
+            },
+            identified: Boolean(metadata.name),
+            ...(!metadata.name && !explicitName
+                ? { warning: `The stream did not publish a station name; saved as ${name}.` }
+                : {})
+        };
+    }
+    catch (error) {
+        if (error instanceof DefiniteStreamError)
+            throw error;
+        const name = explicitName ?? fallbackStationName(url);
+        return {
+            station: stationFromUrl(url, name),
+            identified: false,
+            warning: `Could not read stream metadata; saved as ${name}.`
+        };
+    }
+}
+async function probeStreamHeaders(url, options) {
+    return withExternalResponse(url, {
+        timeoutMs: options.timeoutMs ?? 7_000,
+        fetchImpl: options.fetchImpl,
+        init: {
+            method: 'GET',
+            redirect: 'follow',
+            headers: {
+                accept: 'audio/*, application/ogg, application/vnd.apple.mpegurl, application/x-mpegurl, */*;q=0.1',
+                'icy-metadata': '1'
+            }
+        }
+    }, response => {
+        if (!response.ok) {
+            throw new DefiniteStreamError(`The stream returned HTTP ${response.status}.`);
+        }
+        const contentType = response.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase();
+        if (contentType === 'text/html' || contentType === 'application/json') {
+            throw new DefiniteStreamError('That URL points to a webpage or API response, not a direct radio stream.');
+        }
+        const icyName = sanitizeTerminalText(response.headers.get('icy-name'));
+        const icyDescription = sanitizeTerminalText(response.headers.get('icy-description'));
+        const homepage = safeOptionalHttpUrl(response.headers.get('icy-url'));
+        const bitrate = parseBitrate(response.headers.get('icy-br'), response.headers.get('icy-audio-info'));
+        const codec = codecFromContentType(contentType);
+        const hls = isHls(contentType, url);
+        return {
+            ...(icyName || icyDescription ? { name: icyName ?? icyDescription } : {}),
+            ...(homepage ? { homepage } : {}),
+            ...(codec ? { codec } : {}),
+            ...(bitrate ? { bitrate } : {}),
+            ...(hls ? { hls: true } : {})
+        };
+    });
+}
+/** iHeart stream headers are sometimes unnamed, but their stable numeric stream
+ * id resolves to a canonical public station path without downloading the page. */
+async function probeIHeartListing(url, options) {
+    const parsed = new URL(url);
+    if (!/(?:^|\.)ihrhls\.com$/i.test(parsed.hostname))
+        return undefined;
+    const stationId = /\/zc(\d+)(?:\/|$)/i.exec(parsed.pathname)?.[1]
+        ?? /\/(\d+)_icy(?:\/|$)/i.exec(parsed.pathname)?.[1];
+    if (!stationId)
+        return undefined;
+    return withExternalResponse(`https://www.iheart.com/live/${stationId}/`, {
+        timeoutMs: Math.min(options.timeoutMs ?? 7_000, 4_000),
+        fetchImpl: options.fetchImpl,
+        init: { method: 'HEAD', redirect: 'manual' }
+    }, response => {
+        const location = response.headers.get('location');
+        const slug = location && new RegExp(`^/live/(.+)-${stationId}/?$`, 'i').exec(location)?.[1];
+        if (!slug)
+            return undefined;
+        const name = stationNameFromSlug(slug);
+        return name ? { name, homepage: `https://www.iheart.com${location}` } : undefined;
+    });
+}
+function validatedStreamUrl(input) {
+    const cleaned = safeExternalHttpUrl(input);
+    if (!cleaned)
+        throw new Error('Import requires a direct HTTP(S) stream URL.');
+    const parsed = new URL(cleaned);
+    if (parsed.username || parsed.password)
+        throw new Error('Stream URLs containing credentials are not supported.');
+    return cleaned;
+}
+function safeOptionalHttpUrl(input) {
+    return input ? safeExternalHttpUrl(input) ?? undefined : undefined;
+}
+function parseBitrate(icyBitrate, audioInfo) {
+    const raw = icyBitrate?.match(/\d+/)?.[0] ?? audioInfo?.match(/(?:^|;)\s*bitrate=(\d+)/i)?.[1];
+    const bitrate = Number(raw);
+    return Number.isFinite(bitrate) && bitrate > 0 ? bitrate : undefined;
+}
+function codecFromContentType(contentType) {
+    if (!contentType)
+        return undefined;
+    if (contentType === 'audio/mpeg' || contentType === 'audio/mp3')
+        return 'MP3';
+    if (contentType === 'audio/aac' || contentType === 'audio/aacp')
+        return 'AAC';
+    if (contentType === 'audio/ogg' || contentType === 'application/ogg')
+        return 'OGG';
+    if (contentType === 'audio/flac' || contentType === 'audio/x-flac')
+        return 'FLAC';
+    if (contentType.includes('mpegurl'))
+        return 'HLS';
+    return undefined;
+}
+function isHls(contentType, url) {
+    return Boolean(contentType?.includes('mpegurl') || /\.m3u8(?:$|[?#])/i.test(url));
+}
+function fallbackStationName(url) {
+    const parsed = new URL(url);
+    const segment = decodeURIComponent(parsed.pathname.split('/').filter(Boolean).at(-1) ?? '')
+        .replace(/\.(?:aac|flac|m3u8?|mp3|ogg|opus)$/i, '')
+        .replace(/[-_]+/g, ' ')
+        .trim();
+    return sanitizeTerminalText(segment) ?? parsed.hostname.replace(/^www\./i, '');
+}
+function stationNameFromSlug(slug) {
+    const tokens = slug.split('-').filter(Boolean);
+    const final = tokens.at(-1);
+    const previous = tokens.at(-2);
+    if (final && previous && /^\d$/.test(final) && /^\d{2,3}$/.test(previous)) {
+        tokens.splice(-2, 2, `${previous}.${final}`);
+    }
+    return sanitizeTerminalText(tokens.map(token => {
+        if (/^(?:am|fm|hd\d*)$/i.test(token))
+            return token.toUpperCase();
+        if (/^jamn$/i.test(token))
+            return "JAM'N";
+        if (/^\d{3,4}$/.test(token) && Number(token) >= 881 && Number(token) <= 1079) {
+            return `${token.slice(0, -1)}.${token.slice(-1)}`;
+        }
+        return token.charAt(0).toUpperCase() + token.slice(1);
+    }).join(' '));
+}

package/dist/types.js

@@ -2,3 +2,9 @@ import { defaultReceiverStyle, receiverStyleNames } from './ui/visualizers/recei
 export { defaultReceiverStyle, receiverStyleNames };
 const providerIds = ['radio-browser', 'radio-garden', 'playlist'];
 export const themeNames = ['green', 'amber', 'blue', 'ruby', 'ice', 'teal', 'violet', 'copper', 'cyan', 'lime', 'coral', 'rose', 'slate', 'mono'];
+export const defaultAgentControlSettings = {
+    enabled: false,
+    openUiOnPlay: true,
+    focusNowPlaying: true,
+    completionPreset: { action: 'play', source: 'recent', ifPlaying: 'keep' }
+};