@ciphore/radiocli 0.2.3 → 0.2.4

package/dist/setup.js

@@ -1,24 +1,30 @@
+import { componentLabel, detectPackageManager, packageCommandInvocation, packageInstallCommand, packageInstallPrerequisites, packageManagerElevation, packageManagerNeedsRoot, packageManagerNotes, packageManagerProgram, packageManagers, platformLabel } from './platform/packages.js';
 import { spawn } from 'node:child_process';
-import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
 import { createInterface } from 'node:readline/promises';
-import { clearCommandCache, commandExists } from './player/command.js';
+import { clearCommandCache, commandExists, resolveCommand } from './platform/executables.js';
 import { detectPlaybackBackends, playbackBackendStatusLines } from './player/backend-install.js';
 import { configureMcpIntegrations } from './agent/mcp-install.js';
 import { JsonLibraryStore } from './storage/store.js';
 import { defaultAgentControlSettings } from './types.js';
+import { resolveTerminalCapabilities } from './platform/terminal.js';
+import { identifyPlatform, readLinuxOsRelease } from './platform/runtime.js';
 const components = ['mpv', 'ffmpeg', 'vlc'];
-const packageManagers = ['brew', 'winget', 'scoop', 'choco', 'apt', 'dnf', 'pacman', 'apk', 'zypper'];
 export async function runSetup(options = {}) {
     const platform = options.platform ?? process.platform;
     const osRelease = options.osRelease ?? readLinuxOsRelease(platform);
+    const env = options.env ?? process.env;
+    const host = identifyPlatform({ platform, osRelease, env });
     const input = options.input ?? process.stdin;
     const output = options.output ?? process.stdout;
     const hasCommand = options.hasCommand ?? commandExists;
     const parsed = parseSetupArgs(options.args ?? []);
+    if (parsed.packageManager)
+        validateNativePackageManager(parsed.packageManager, host);
     const installed = detectInstalledComponents(hasCommand);
-    const packageManager = parsed.packageManager ?? detectPackageManager(platform, osRelease, hasCommand);
+    const packageManager = parsed.packageManager ?? detectPackageManager(platform, osRelease, hasCommand, env);
     writeHeader(output);
-    output.write(`System  ${platformLabel(platform, osRelease)} · Node ${process.version}\n`);
+    output.write(`System  ${platformLabel(platform, osRelease, env)} ${separator(output)} Node ${process.version}\n`);
     output.write(`Manager ${packageManager ?? 'not detected'}\n\n`);
     let selected = parsed.only ?? defaultComponents(platform, parsed.all);
     if (!parsed.yes && !parsed.only && isInteractive(input, output)) {
@@ -35,8 +41,15 @@ export async function runSetup(options = {}) {
             : ' (opens a separate terminal window)';
         agentUi = await promptYesNo(input, output, `  Open the RadioCLI TUI for agent playback${note}`, true);
     }
-    const plan = createSetupPlan({ platform, osRelease, packageManager, installed, selected });
+    const isRoot = (options.getUid ?? process.getuid)?.() === 0;
+    const elevation = packageManagerElevation(hasCommand, isRoot);
+    const plan = createSetupPlan({ platform, osRelease, env, packageManager, installed, selected, elevation });
     printPlan(plan, output);
+    if (packageManager && packageManagerNeedsRoot(packageManager) && !isRoot && !elevation) {
+        output.write('  Note: Run package commands as root; sudo/doas unavailable.\n');
+    }
+    for (const note of packageManagerNotes(packageManager, host))
+        output.write(`  Note: ${note}\n`);
     const missing = plan.selected.filter(component => !plan.installed[component]);
     if (missing.length === 0) {
         output.write(plan.selected.length === 0 ? '\nNo components selected.\n' : '\nEverything selected is already installed.\n');
@@ -57,8 +70,17 @@ export async function runSetup(options = {}) {
         await finishMcpSetup(mcp, agentUi, true, output);
         return;
     }
-    if (parsed.packageManager && !hasCommand(parsed.packageManager)) {
-        throw new Error(`Requested package manager is not available: ${parsed.packageManager}.`);
+    const manual = missing.filter(component => !plan.commands.some(command => command.component === component));
+    if (manual.length)
+        throw new Error(`No verified automatic installation command for ${manual.join(', ')} with ${plan.packageManager}. Install these components manually or select --only=mpv.`);
+    if (plan.packageManager === 'termux-pkg' && isRoot)
+        throw new Error('Run setup as the normal Termux app user. Termux pkg refuses root execution.');
+    if (packageManagerNeedsRoot(plan.packageManager) && !isRoot && !elevation) {
+        throw new Error('System package installation requires root, sudo, or doas. Review the dry-run plan and install prerequisites with your administrator.');
+    }
+    if (parsed.packageManager && !hasCommand(packageManagerProgram(parsed.packageManager))) {
+        const program = packageManagerProgram(parsed.packageManager);
+        throw new Error(`Requested package manager is not available: ${parsed.packageManager}${program !== parsed.packageManager ? ` (${program})` : ''}.`);
     }
     if (!parsed.yes && isInteractive(input, output)) {
         const confirmed = await promptYesNo(input, output, '\nInstall these components?', true);
@@ -72,9 +94,9 @@ export async function runSetup(options = {}) {
     }
     if (plan.commands.some(command => command.program === 'sudo')) {
         output.write('\nRadioCLI needs administrator approval for the system package manager.\n');
-        await runVisibleCommand('sudo', ['-v']);
+        await runVisibleCommand(resolveCommand('sudo') ?? 'sudo', ['-v']);
     }
-    const execute = options.runCommand ?? runInstallCommand;
+    const execute = options.runCommand ?? ((command, destination) => runInstallCommand(command, destination, platform));
     output.write('\nInstalling\n');
     for (const command of plan.commands) {
         await execute(command, output);
@@ -84,48 +106,32 @@ export async function runSetup(options = {}) {
     await finishMcpSetup(mcp, agentUi, false, output);
     printVerification(output);
 }
-export function createSetupPlan({ platform, osRelease = '', packageManager, installed, selected }) {
+export function createSetupPlan({ platform, osRelease = '', env = process.env, packageManager, installed, selected, elevation = 'sudo' }) {
+    if (packageManager)
+        validateNativePackageManager(packageManager, identifyPlatform({ platform, osRelease, env }));
     const uniqueSelected = components.filter(component => selected.includes(component));
     const missing = uniqueSelected.filter(component => !installed[component]);
-    const commands = packageManager ? missing.map(component => packageInstallCommand(packageManager, component)) : [];
-    if (packageManager === 'scoop' && missing.some(component => component === 'mpv' || component === 'vlc')) {
-        commands.unshift({
-            component: null,
-            label: 'Scoop extras bucket',
-            program: 'scoop',
-            args: ['bucket', 'add', 'extras'],
-            display: 'scoop bucket add extras'
-        });
-    }
+    const commands = packageManager ? missing.map(component => packageInstallCommand(packageManager, component, { elevation })).filter((command) => command !== null) : [];
+    if (packageManager)
+        commands.unshift(...packageInstallPrerequisites(packageManager, missing));
     return {
         platform,
-        platformLabel: platformLabel(platform, osRelease),
+        platformLabel: platformLabel(platform, osRelease, env),
         packageManager,
         installed,
         selected: uniqueSelected,
         commands
     };
 }
-export function detectPackageManager(platform, osRelease, hasCommand = commandExists) {
-    if (platform === 'darwin')
-        return hasCommand('brew') ? 'brew' : null;
-    if (platform === 'win32')
-        return firstAvailable(['winget', 'scoop', 'choco'], hasCommand);
-    if (platform !== 'linux')
-        return null;
-    const ids = linuxReleaseIds(osRelease);
-    const preferred = hasAny(ids, ['debian', 'ubuntu', 'linuxmint', 'pop'])
-        ? ['apt']
-        : hasAny(ids, ['fedora', 'rhel', 'centos'])
-            ? ['dnf']
-            : hasAny(ids, ['arch', 'manjaro'])
-                ? ['pacman']
-                : hasAny(ids, ['alpine'])
-                    ? ['apk']
-                    : hasAny(ids, ['opensuse', 'suse'])
-                        ? ['zypper']
-                        : ['apt', 'dnf', 'pacman', 'apk', 'zypper'];
-    return firstAvailable(preferred, hasCommand);
+function validateNativePackageManager(manager, host) {
+    const required = host.id === 'termux' ? 'termux-pkg' : host.id === 'haiku' ? 'pkgman' : host.id === 'sunos' ? 'pkgin' : null;
+    if ((required && manager !== required)
+        || (manager === 'termux-pkg' && host.id !== 'termux')
+        || (manager === 'pkgman' && host.id !== 'haiku')
+        || (manager === 'pkg' && host.id !== 'freebsd')
+        || ['aix', 'android', 'unknown'].includes(host.id)) {
+        throw new Error(`No verified ${manager} playback package recipe for ${host.id}.${required ? ` Use --package-manager=${required}.` : ' Install a native player manually and run radiocli doctor.'}`);
+    }
 }
 export function parseSetupArgs(args) {
     let all = false;
@@ -220,51 +226,6 @@ function parsePackageManager(value) {
     }
     return value;
 }
-function packageInstallCommand(manager, component) {
-    const packages = {
-        brew: { mpv: 'mpv', ffmpeg: 'ffmpeg', vlc: 'vlc' },
-        winget: { mpv: 'shinchiro.mpv', ffmpeg: 'Gyan.FFmpeg', vlc: 'VideoLAN.VLC' },
-        scoop: { mpv: 'mpv', ffmpeg: 'ffmpeg', vlc: 'vlc' },
-        choco: { mpv: 'mpv', ffmpeg: 'ffmpeg', vlc: 'vlc' },
-        apt: { mpv: 'mpv', ffmpeg: 'ffmpeg', vlc: 'vlc' },
-        dnf: { mpv: 'mpv', ffmpeg: 'ffmpeg', vlc: 'vlc' },
-        pacman: { mpv: 'mpv', ffmpeg: 'ffmpeg', vlc: 'vlc' },
-        apk: { mpv: 'mpv', ffmpeg: 'ffmpeg', vlc: 'vlc' },
-        zypper: { mpv: 'mpv', ffmpeg: 'ffmpeg', vlc: 'vlc' }
-    };
-    const packageName = packages[manager][component];
-    let program = manager;
-    let args;
-    if (manager === 'brew')
-        args = ['install', component === 'vlc' ? '--cask' : packageName, ...(component === 'vlc' ? [packageName] : [])];
-    else if (manager === 'winget')
-        args = ['install', '--id', packageName, '-e', '--accept-package-agreements', '--accept-source-agreements'];
-    else if (manager === 'scoop')
-        args = ['install', packageName];
-    else if (manager === 'choco')
-        args = ['install', packageName, '-y'];
-    else if (manager === 'apt') {
-        program = 'sudo';
-        args = ['apt-get', 'install', '-y', packageName];
-    }
-    else if (manager === 'dnf') {
-        program = 'sudo';
-        args = ['dnf', 'install', '-y', packageName];
-    }
-    else if (manager === 'pacman') {
-        program = 'sudo';
-        args = ['pacman', '-S', '--needed', '--noconfirm', packageName];
-    }
-    else if (manager === 'apk') {
-        program = 'sudo';
-        args = ['apk', 'add', packageName];
-    }
-    else {
-        program = 'sudo';
-        args = ['zypper', '--non-interactive', 'install', packageName];
-    }
-    return { component, label: componentLabel(component), program, args, display: [program, ...args].join(' ') };
-}
 function defaultComponents(platform, all) {
     if (all)
         return [...components];
@@ -280,11 +241,11 @@ function detectInstalledComponents(hasCommand) {
 async function promptForComponents({ platform, installed, input, output }) {
     output.write('Choose components (installed items will be skipped):\n');
     const selected = [];
-    if (await promptYesNo(input, output, `  mpv      Full playback controls${installed.mpv ? ' · installed' : ''}`, true))
+    if (await promptYesNo(input, output, `  mpv      Full playback controls${installed.mpv ? ` ${separator(output)} installed` : ''}`, true))
         selected.push('mpv');
-    if (await promptYesNo(input, output, `  FFmpeg   ${platform === 'darwin' ? 'AirPlay + ' : ''}ffplay fallback${installed.ffmpeg ? ' · installed' : ''}`, platform === 'darwin'))
+    if (await promptYesNo(input, output, `  FFmpeg   ${platform === 'darwin' ? 'AirPlay + ' : ''}ffplay fallback${installed.ffmpeg ? ` ${separator(output)} installed` : ''}`, platform === 'darwin'))
         selected.push('ffmpeg');
-    if (await promptYesNo(input, output, `  VLC      Additional playback fallback${installed.vlc ? ' · installed' : ''}`, false))
+    if (await promptYesNo(input, output, `  VLC      Additional playback fallback${installed.vlc ? ` ${separator(output)} installed` : ''}`, false))
         selected.push('vlc');
     return selected;
 }
@@ -302,19 +263,23 @@ async function promptYesNo(input, output, question, defaultValue) {
 }
 function printPlan(plan, output) {
     output.write('\nInstallation plan\n');
+    for (const command of plan.commands.filter(command => command.component === null)) {
+        output.write(`  ${pendingMark(output)} ${command.label} ${separator(output)} ${command.display}\n`);
+    }
     for (const component of plan.selected) {
         if (plan.installed[component])
             output.write(`  ${successMark(output)} ${componentLabel(component)} already installed\n`);
         else {
             const command = plan.commands.find(candidate => candidate.component === component);
-            output.write(`  ${pendingMark(output)} ${componentLabel(component)}${command ? ` · ${command.display}` : ' · manual installation required'}\n`);
+            output.write(`  ${pendingMark(output)} ${componentLabel(component)} ${separator(output)} ${command ? command.display : 'manual installation required'}\n`);
         }
     }
     if (plan.selected.length === 0)
         output.write('  No components selected\n');
 }
-async function runInstallCommand(command, output) {
-    const interactive = Boolean(output.isTTY);
+async function runInstallCommand(command, output, platform) {
+    const terminal = setupTerminal(output);
+    const interactive = terminal.interactive && !terminal.reduceMotion;
     const startedAt = Date.now();
     let timer;
     let frame = 0;
@@ -330,7 +295,8 @@ async function runInstallCommand(command, output) {
     }
     try {
         await new Promise((resolve, reject) => {
-            const child = spawn(command.program, command.args, { stdio: ['inherit', 'pipe', 'pipe'] });
+            const invocation = packageCommandInvocation(command, platform, resolveCommand);
+            const child = spawn(invocation.program, invocation.args, { shell: false, stdio: ['inherit', 'pipe', 'pipe'] });
             child.stdout?.on('data', chunk => { stdout = tail(`${stdout}${String(chunk)}`); });
             child.stderr?.on('data', chunk => { stderr = tail(`${stderr}${String(chunk)}`); });
             child.once('error', reject);
@@ -358,8 +324,9 @@ function progressFrame(label, frame, elapsedMs, output) {
     const cycle = travel * 2;
     const offset = frame % cycle;
     const start = offset <= travel ? offset : cycle - offset;
-    const bar = Array.from({ length: width }, (_, index) => index >= start && index < start + segment ? '█' : '░').join('');
-    return `  ${accent(output, '◒')} ${accent(output, `[${bar}]`)} Installing ${label} ${formatElapsed(elapsedMs)}`;
+    const unicode = setupTerminal(output).unicode;
+    const bar = Array.from({ length: width }, (_, index) => index >= start && index < start + segment ? (unicode ? '█' : '#') : (unicode ? '░' : '.')).join('');
+    return `  ${accent(output, unicode ? '◒' : '*')} ${accent(output, `[${bar}]`)} Installing ${label} ${formatElapsed(elapsedMs)}`;
 }
 function printVerification(output) {
     clearCommandCache();
@@ -372,41 +339,34 @@ function printVerification(output) {
 }
 function writeHeader(output) {
     output.write(`${accent(output, 'RADIOCLI')}  SETUP RECEIVER\n`);
-    output.write(`${accent(output, '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}\n`);
-}
-function platformLabel(platform, osRelease) {
-    if (platform === 'darwin')
-        return `${process.arch === 'arm64' ? 'macOS Apple Silicon' : 'macOS'}`;
-    if (platform === 'win32')
-        return 'Windows';
-    if (platform === 'linux')
-        return osReleaseValue(osRelease, 'PRETTY_NAME') || 'Linux';
-    return platform;
-}
-function componentLabel(component) {
-    if (component === 'ffmpeg')
-        return 'FFmpeg / ffplay';
-    if (component === 'vlc')
-        return 'VLC fallback';
-    return 'mpv';
+    output.write(`${accent(output, setupTerminal(output).unicode ? '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━' : '------------------------------------')}\n`);
 }
 function isInteractive(input, output) {
     return Boolean(input.isTTY && output.isTTY);
 }
 function accent(output, value) {
-    return colorsEnabled(output) ? `\u001b[38;2;116;242;138m${value}\u001b[0m` : value;
+    const level = setupTerminal(output).colorLevel;
+    const color = level === 3 ? '38;2;116;242;138' : level === 2 ? '38;5;120' : '32';
+    return level > 0 ? `\u001b[${color}m${value}\u001b[0m` : value;
 }
 function successMark(output) {
-    return accent(output, '✓');
+    return accent(output, setupTerminal(output).unicode ? '✓' : '+');
 }
 function pendingMark(output) {
-    return accent(output, '◆');
+    return accent(output, setupTerminal(output).unicode ? '◆' : '*');
 }
 function failureMark(output) {
-    return colorsEnabled(output) ? '\u001b[38;2;255;95;135m✗\u001b[0m' : '✗';
+    const terminal = setupTerminal(output);
+    const value = terminal.unicode ? '✗' : 'x';
+    const color = terminal.colorLevel === 3 ? '38;2;255;95;135' : terminal.colorLevel === 2 ? '38;5;204' : '31';
+    return terminal.colorLevel > 0 ? `\u001b[${color}m${value}\u001b[0m` : value;
+}
+function setupTerminal(output) {
+    const stream = output;
+    return resolveTerminalCapabilities(process.env, { isTTY: Boolean(stream.isTTY), colorDepth: stream.getColorDepth?.() });
 }
-function colorsEnabled(output) {
-    return Boolean(output.isTTY) && !process.env.NO_COLOR;
+function separator(output) {
+    return setupTerminal(output).unicode ? '·' : '-';
 }
 function clearLine() {
     return '\u001b[2K';
@@ -428,35 +388,3 @@ async function runVisibleCommand(program, args) {
         child.once('close', code => code === 0 ? resolve() : reject(new Error(`${program} ${args.join(' ')} exited with code ${code}.`)));
     });
 }
-function firstAvailable(values, hasCommand) {
-    return values.find(hasCommand) ?? null;
-}
-function readLinuxOsRelease(platform) {
-    if (platform !== 'linux' || !existsSync('/etc/os-release'))
-        return '';
-    try {
-        return readFileSync('/etc/os-release', 'utf8');
-    }
-    catch {
-        return '';
-    }
-}
-function linuxReleaseIds(osRelease) {
-    const ids = new Set();
-    for (const line of osRelease.split('\n')) {
-        const match = /^(ID|ID_LIKE)=(.*)$/.exec(line);
-        if (!match)
-            continue;
-        for (const value of match[2].replaceAll('"', '').split(/\s+/))
-            if (value.trim())
-                ids.add(value.trim().toLowerCase());
-    }
-    return ids;
-}
-function osReleaseValue(osRelease, key) {
-    const line = osRelease.split('\n').find(candidate => candidate.startsWith(`${key}=`));
-    return line?.slice(key.length + 1).replace(/^"|"$/g, '') ?? '';
-}
-function hasAny(values, candidates) {
-    return candidates.some(candidate => values.has(candidate));
-}

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({
@@ -234,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());
@@ -496,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) {
@@ -535,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();
         }
     }
@@ -560,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) {
@@ -602,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 ?? '');
@@ -700,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),
@@ -768,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 [