@ciphore/radiocli 0.2.4 → 0.2.6

package/dist/cli/completion.js

@@ -0,0 +1,44 @@
+export function completionScript(shell) {
+    if (shell === 'bash')
+        return `# RadioCLI Bash completion
+_radiocli_complete() {
+  local candidate
+  COMPREPLY=()
+  while IFS= read -r candidate; do
+    COMPREPLY+=("$candidate")
+  done < <(radiocli _complete "\${COMP_WORDS[@]:1:COMP_CWORD}" 2>/dev/null)
+}
+complete -F _radiocli_complete radiocli
+`;
+    if (shell === 'zsh')
+        return `# RadioCLI Zsh completion (load after compinit)
+_radiocli_complete() {
+  local -a candidates
+  candidates=("\${(@f)$(radiocli _complete "\${words[@]:1:$((CURRENT - 1))}" 2>/dev/null)}")
+  compadd -- "\${candidates[@]}"
+}
+compdef _radiocli_complete radiocli
+`;
+    if (shell === 'fish')
+        return `# RadioCLI Fish completion
+function __radiocli_candidates
+  set -l words (commandline -opc)
+  set -e words[1]
+  set -l current (commandline -ct)
+  radiocli _complete $words "$current" 2>/dev/null
+end
+complete -c radiocli -f -a '(__radiocli_candidates)'
+`;
+    if (shell === 'powershell')
+        return `# RadioCLI PowerShell completion
+Register-ArgumentCompleter -Native -CommandName radiocli -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $words = @($commandAst.CommandElements | Select-Object -Skip 1 | Where-Object { $_.Extent.StartOffset -lt $cursorPosition } | ForEach-Object { $_.Extent.Text })
+  if (!$wordToComplete) { $words += '' }
+  & radiocli _complete @words 2>$null | ForEach-Object {
+    [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+  }
+}
+`;
+    throw new Error('Choose a completion shell: bash, zsh, fish, or powershell. Run radiocli completion --help.');
+}

package/dist/cli/doctor.js

@@ -0,0 +1,156 @@
+import { defaultLibraryPath } from '../storage/store.js';
+import { detectPlaybackBackends, playbackBackendStatusLines } from '../player/backend-install.js';
+import { resolveCommand } from '../platform/executables.js';
+import { diagnoseCommand } from '../player/command-diagnostics.js';
+import { readSettingsWithoutMigration } from '../storage/read-settings.js';
+import { airPlaySenderHealth } from '../player/airplay-sender-health.js';
+import { appVersion } from '../version.js';
+import { identifyPlatform } from '../platform/runtime.js';
+import { platformCapabilities } from '../platform/capabilities.js';
+import { hasGraphicalSession } from '../platform/desktop.js';
+import { detectPackageManager } from '../platform/packages.js';
+import { storageReadiness } from '../platform/storage.js';
+import { resolveTerminalCapabilities } from '../platform/terminal.js';
+import { networkDiagnostic } from '../platform/network.js';
+import { assessPlatformSupport } from '../platform/support.js';
+export async function runDoctor(rest) {
+    const saved = (() => { try {
+        return readSettingsWithoutMigration(defaultLibraryPath());
+    }
+    catch {
+        return undefined;
+    } })();
+    const backends = detectPlaybackBackends({ settings: { linuxAirPlayEnabled: saved?.linuxAirPlayEnabled === true } });
+    const mpvDiagnostic = diagnoseCommand('mpv');
+    const base = await doctorReport(backends, mpvDiagnostic);
+    const playbackRehearsal = rest.includes('--playback') ? await (await import('../setup-playback.js')).verifyLocalPlayback(backends) : undefined;
+    const report = { ...base, ...(playbackRehearsal ? { playbackRehearsal } : {}) };
+    if (rest.includes('--json')) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log(`backends=${backends.join(',') || 'none'}`);
+    printMpvDiagnostic(report.mpv);
+    for (const line of playbackBackendStatusLines(backends))
+        console.log(line);
+    for (const [name, capability] of Object.entries(report.capabilities)) {
+        console.log(`capability_${name}=${capability.status} ${capability.message}`);
+    }
+    console.log(`omarchy=${report.omarchy.kind} status=${report.omarchy.status} version=${report.omarchy.version ?? 'unknown'} source=${report.omarchy.source ?? 'none'}`);
+    if (report.omarchy.session)
+        console.log(`desktop_session=${report.omarchy.session.type} remote=${report.omarchy.session.remote ? 'yes' : 'no'}`);
+    console.log(`omarchy_launcher=${report.omarchy.terminal.prerequisitesReady ? 'ready' : 'unavailable'} missing=${report.omarchy.terminal.missing.join(',') || 'none'}`);
+    console.log(`desktop_media_preference=${report.desktopMedia.preference.value} source=${report.desktopMedia.preference.source} status=${report.desktopMedia.preference.status}`);
+    console.log(`desktop_media_policy=${report.desktopMedia.policy.status} eligible=${report.desktopMedia.policy.eligible ? 'yes' : 'no'} ${report.desktopMedia.policy.message}`);
+    console.log(`desktop_media_bus=${report.desktopMedia.sessionBus.status} ${report.desktopMedia.sessionBus.message}`);
+    console.log(`desktop_media_owner=${report.desktopMedia.owner.status} ${report.desktopMedia.owner.message}`);
+    console.log(`terminal_launcher=${report.terminalLauncher.selected ?? 'none'} prerequisites=${report.terminalLauncher.prerequisites} launch=${report.terminalLauncher.launch} ${report.terminalLauncher.message}`);
+    console.log(`audio_session=${report.audio.status} backend=${report.audio.backend ?? 'none'} ${report.audio.message}`);
+    if (playbackRehearsal) {
+        for (const rehearsal of playbackRehearsal)
+            console.log(`decoder_${rehearsal.backend}=${rehearsal.status} ${rehearsal.message}`);
+        if (!playbackRehearsal.length)
+            console.log('decoder=unverified No local playback backend is available for a rehearsal.');
+        console.log('physical_output=unverified Null/dummy playback does not verify speakers, headphones, receivers, or a live network stream.');
+    }
+    console.log(`airplay_readiness=${report.airPlay.state !== 'enabled' ? report.airPlay.state : report.airPlay.ready ? 'ready' : 'unavailable'} discovery=${report.airPlay.discoveryService} sender=${report.airPlay.senderLoaded ? 'loaded' : 'unavailable'} ${report.airPlay.message}`);
+    console.log(`network=${report.network.status} ${report.network.message}`);
+    console.log(`support_tier=${report.support.tier} runtime=${report.support.runtime.status}`);
+    console.log(`support_scope=${report.support.scope}`);
+    console.log('support_note=Doctor checks this installation without running packed-install or audio acceptance tests; reference CI results are documented in the platform matrix.');
+    for (const reason of report.support.reasons)
+        console.log(`support_note=${reason}`);
+}
+async function doctorReport(backends, mpvDiagnostic) {
+    const commands = Object.fromEntries(['mpv', 'ffplay', 'vlc', 'cvlc', 'ffmpeg', 'dns-sd'].map(command => [command, redactHome(resolveCommand(command))]));
+    const airPlay = airPlaySenderHealth();
+    const host = identifyPlatform();
+    const { probeNativeIntegrations, probeDoctorScheduler } = await import('../platform/diagnostics.js');
+    const native = await probeNativeIntegrations({ host, libraryPath: defaultLibraryPath });
+    const terminal = resolveTerminalCapabilities(process.env, { isTTY: Boolean(process.stdout.isTTY), colorDepth: process.stdout.getColorDepth?.() });
+    const scheduler = await probeDoctorScheduler(host);
+    const integrationCommands = [
+        'launchctl', 'schtasks.exe', 'systemctl', 'caffeinate', 'systemd-inhibit',
+        'powershell.exe', 'pwsh.exe', 'osascript', 'wpctl', 'pactl', 'amixer',
+        'open', 'explorer', 'xdg-open', 'pbcopy', 'clip', 'wl-copy', 'xclip', 'xsel',
+        'termux-open-url', 'termux-clipboard-set'
+    ].filter(command => resolveCommand(command) !== null);
+    const capabilities = platformCapabilities(host, {
+        backends,
+        commands: integrationCommands,
+        graphicalSession: hasGraphicalSession(host),
+        packageManager: detectPackageManager(process.platform, host.osRelease),
+        storageWritable: libraryWritesAvailable(),
+        scheduler,
+        unicode: terminal.unicode,
+        color: terminal.colorLevel > 0,
+        screenReader: terminal.screenReader,
+        airPlay: native.airPlay
+    });
+    return {
+        radioCliVersion: appVersion(),
+        nodeVersion: process.version,
+        platform: process.platform,
+        architecture: process.arch,
+        host: { id: host.id, arch: host.arch, armVersion: host.armVersion, endianness: host.endianness, release: host.release, libc: host.libc, isWsl: host.isWsl },
+        support: { scope: 'current-installation', ...assessPlatformSupport(host) },
+        capabilities,
+        terminal,
+        omarchy: native.omarchy,
+        desktopMedia: native.desktopMedia,
+        terminalLauncher: native.terminalLauncher,
+        audio: native.audio,
+        network: networkDiagnostic(),
+        backends,
+        commands,
+        mpv: redactDiagnostic(mpvDiagnostic),
+        airPlay: {
+            available: airPlay.available,
+            safe: airPlay.safe,
+            package: airPlay.packageName,
+            version: airPlay.version ?? null,
+            vulnerablePackages: airPlay.vulnerablePackages,
+            warningPackages: airPlay.warningPackages,
+            ...native.airPlay
+        },
+        guidance: playbackBackendStatusLines(backends)
+    };
+}
+function libraryWritesAvailable() {
+    try {
+        return storageReadiness(defaultLibraryPath()).status === 'available';
+    }
+    catch {
+        return false;
+    }
+}
+function printMpvDiagnostic(diagnostic) {
+    console.log(`mpv_path=${redactHome(diagnostic.path) ?? 'not-found'}`);
+    console.log(`mpv_discovery=${diagnostic.discovery}`);
+    console.log(`mpv_launch=${diagnostic.launchable ? 'ready' : 'failed'}`);
+    if (diagnostic.version)
+        console.log(`mpv_version=${diagnostic.version}`);
+    if (diagnostic.error)
+        console.log(`mpv_error=${diagnostic.error}`);
+    if (diagnostic.launchable && diagnostic.discovery !== 'path') {
+        console.log('mpv_hint=RadioCLI found mpv outside PATH and can use it directly; no PATH changes are required.');
+    }
+    else if (!diagnostic.path && process.platform === 'win32') {
+        console.log('mpv_hint=Install with winget, then rerun Doctor; RadioCLI also checks the standard MPV Player install directory.');
+    }
+}
+function redactDiagnostic(diagnostic) {
+    // Executable banners and spawn errors can include private build paths, URLs,
+    // or environment values. Keep a bounded version token and actionable status.
+    const version = diagnostic.version?.slice(0, 256).match(/^mpv\s+(v?\d+(?:\.\d+){1,3}(?:[a-z\d.+-]{0,80})?)(?:\s|$)/i)?.[1];
+    const error = diagnostic.error === null ? null : diagnostic.discovery === 'missing' ? 'not found'
+        : diagnostic.discovery === 'configured-path' ? 'The configured mpv executable could not be run. Check RADIOCLI_MPV_PATH.'
+            : 'mpv could not be launched. Check the executable and its native runtime dependencies.';
+    return { ...diagnostic, path: redactHome(diagnostic.path), version: version ? `mpv ${version}` : null, error };
+}
+function redactHome(path) {
+    if (!path)
+        return null;
+    const home = process.env.HOME ?? process.env.USERPROFILE;
+    return home && path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}

package/dist/cli/interactive.js

@@ -0,0 +1,79 @@
+import { createInterface } from 'node:readline';
+import { setTimeout as delay } from 'node:timers/promises';
+export function requireInteractive(action) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        throw new Error(`${action} needs an interactive terminal. Use --json or --plain for scripts, and radiocli play <provider:id> to select a station directly.`);
+}
+/** A small line-mode chooser preserves scrollback and ordinary terminal editing. */
+export async function pickStation(stations, output, favorites) {
+    requireInteractive('--pick');
+    if (!stations.length)
+        throw new Error('No stations found. Try a broader search or remove a filter.');
+    output.stations(stations, favorites, undefined, false);
+    const input = createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const cancel = () => {
+            if (settled)
+                return;
+            settled = true;
+            reject(Object.assign(new Error('Selection cancelled.'), { name: 'AbortError' }));
+            input.close();
+        };
+        input.once('SIGINT', cancel);
+        input.once('close', cancel);
+        const ask = () => input.question(`Play station [1-${stations.length}], or q to cancel: `, answer => {
+            if (answer.trim().toLowerCase() === 'q' || !answer.trim()) {
+                cancel();
+                return;
+            }
+            const index = /^\d+$/.test(answer.trim()) ? Number(answer.trim()) - 1 : -1;
+            const station = stations[index];
+            if (!station) {
+                process.stderr.write(`Choose a number from 1 through ${stations.length}.\n`);
+                ask();
+                return;
+            }
+            settled = true;
+            input.close();
+            resolve(station);
+        });
+        ask();
+    });
+}
+export async function watchNow(read, output) {
+    requireInteractive('--watch');
+    const controller = new AbortController();
+    const interrupt = () => { process.exitCode = 130; controller.abort(); };
+    const terminate = () => { process.exitCode = 143; controller.abort(); };
+    process.once('SIGINT', interrupt);
+    process.once('SIGTERM', terminate);
+    const rewrite = output.terminal.interactive && !output.terminal.screenReader;
+    let rendered = false;
+    let previous = '';
+    try {
+        process.stderr.write('Watching playback. Ctrl+C exits this view; audio continues.\n');
+        while (!controller.signal.aborted) {
+            const status = await read(controller.signal);
+            if (controller.signal.aborted)
+                break;
+            const line = output.fit(output.nowLine(status), Math.max(1, (process.stdout.columns || 100) - 1));
+            if (!rendered || line !== previous) {
+                process.stdout.write(rewrite ? `\r\u001b[2K${line}` : `${line}\n`);
+                rendered = true;
+                previous = line;
+            }
+            await delay(1000, undefined, { signal: controller.signal });
+        }
+    }
+    catch (error) {
+        if (!controller.signal.aborted)
+            throw error;
+    }
+    finally {
+        process.removeListener('SIGINT', interrupt);
+        process.removeListener('SIGTERM', terminate);
+        if (rendered && rewrite)
+            process.stdout.write('\n');
+    }
+}

package/dist/cli/listener.js

@@ -0,0 +1,227 @@
+import { randomInt } from 'node:crypto';
+import { AgentRadioService } from '../agent/service.js';
+import { connectRadioSession } from '../agent/session.js';
+import { connectActiveAlarms } from '../alarms/active-session.js';
+import { JsonLibraryStore, stationKey } from '../storage/store.js';
+import { matchesStationId } from '../storage/station-identity.js';
+import { ProviderManager } from '../providers/provider-manager.js';
+import { computeListeningStats } from '../activity/stats.js';
+import { integerOption, parseListenerArgs } from './arguments.js';
+import { CliOutput, clean } from './output.js';
+import { pickStation, requireInteractive, watchNow } from './interactive.js';
+import { completionScript } from './completion.js';
+export async function runListenerCommand(command, args, runtime) {
+    const parsed = parseListenerArgs(command, args);
+    const { words, flags, options } = parsed;
+    if (command === 'completion') {
+        if (words.length !== 1)
+            throw new Error('Usage: radiocli completion <bash|zsh|fish|powershell>');
+        const script = completionScript(words[0]);
+        if (!flags.quiet)
+            console.log(flags.json ? JSON.stringify(script) : script);
+        return;
+    }
+    if (options.has('--pick'))
+        requireInteractive('--pick');
+    if (options.has('--watch'))
+        requireInteractive('--watch');
+    const store = new JsonLibraryStore();
+    const state = store.snapshot();
+    const providers = new ProviderManager();
+    const service = new AgentRadioService(runtime, store, providers, 'cli');
+    const output = new CliOutput(flags, state.settings);
+    const query = words.join(' ').trim();
+    const filters = searchOptions(parsed);
+    const noWords = () => { if (words.length)
+        throw new Error(`Unexpected argument: ${clean(words[0])}\nRun radiocli ${command} --help.`); };
+    const finish = (result, background = false) => {
+        if (!result.ok && (output.mode !== 'json' || flags.quiet))
+            throw new Error(result.message);
+        output.result(result, background);
+        if (!result.ok)
+            process.exitCode = 1;
+    };
+    const select = async (stations, forcePick = options.has('--pick')) => {
+        if (!stations.length)
+            throw new Error('No stations found. Try radiocli search with a broader query, or radiocli favorites.');
+        if (stations.length === 1 && !forcePick)
+            return stations[0];
+        if (process.stdin.isTTY && process.stdout.isTTY && output.mode === 'human' && !flags.noInput && !flags.quiet)
+            return pickStation(stations, output, state.favorites);
+        const target = command === 'preset' ? 'preset save <name>' : command === 'search' ? 'play' : command;
+        throw new Error(`Several stations match. Use an exact provider:id with radiocli ${target}:\n${stations.slice(0, 20).map(station => `  ${clean(stationKey(station))}  ${clean(station.name)}`).join('\n')}`);
+    };
+    const saved = uniqueStations([...state.favorites, ...state.imported, ...state.recent.map(item => item.station), ...(state.presets ?? []).map(preset => preset.station)]);
+    const resolve = async (text) => {
+        if (/^https?:\/\//i.test(text))
+            throw new Error('Import a stream first with radiocli import <stream-url>, then play its saved name or ID.');
+        const preset = (state.presets ?? []).find(item => item.name === normalize(text));
+        const exactIds = saved.filter(station => matchesStationId(station, text));
+        if (preset || exactIds.length) {
+            const station = preset?.station ?? await select(exactIds);
+            if (!matchesFilters(station, filters))
+                throw new Error('The selected saved station does not match those filters. Remove the filters or search for another station.');
+            return { station, queue: [station] };
+        }
+        if (/^(radio-browser|radio-garden|playlist):/.test(text)) {
+            const split = text.indexOf(':');
+            const station = await providers.byId(text.slice(0, split), text.slice(split + 1));
+            if (!station)
+                throw new Error(`Station not found: ${clean(text)}. Use radiocli search to find a current ID, or import this station into your library.`);
+            if (!matchesFilters(station, filters))
+                throw new Error('The station does not match those filters.');
+            return { station, queue: [station] };
+        }
+        const matching = saved.filter(station => matchesFilters(station, filters));
+        const exact = matching.filter(station => normalize(station.name) === normalize(text));
+        const local = exact.length ? exact : matching.filter(station => normalize(text).split(/\s+/).every(word => normalize(station.name).includes(word)));
+        const stations = local.length ? local : await providers.search(text, state.settings, filters);
+        const remoteExact = stations.filter(station => normalize(station.name) === normalize(text));
+        const candidates = remoteExact.length && !options.has('--pick') ? remoteExact : stations;
+        const station = options.has('--random') && stations.length ? stations[randomInt(stations.length)] : await select(candidates);
+        return { station, queue: stations };
+    };
+    const currentStation = async () => {
+        const station = (await readStatus())?.station;
+        if (!station)
+            throw new Error('No station is playing. Supply a station name, or start playback with radiocli play "station name".');
+        return station;
+    };
+    if (command === 'now' || command === 'status') {
+        noWords();
+        if (options.has('--watch'))
+            await watchNow(readStatus, output);
+        else
+            output.now(await readStatus());
+        return;
+    }
+    if (command === 'play') {
+        if (options.has('--random') && options.has('--pick'))
+            throw new Error('Choose either --random or --pick.');
+        if (query && options.has('--source'))
+            throw new Error('Choose a station name or a station queue (--favorites, --recent, --popular, or --source).');
+        const selectingStation = query || ['--source', '--random', '--pick', '--country', '--language', '--codec', '--min-bitrate', '--limit'].some(option => options.has(option));
+        const active = selectingStation ? null : await readStatus();
+        if (active?.station && ['paused', 'playing', 'loading'].includes(active.playback.state)) {
+            if ((await connectActiveAlarms()).length)
+                throw new Error('An alarm is currently active. Dismiss or keep the alarm from its ringing controls before starting interactive playback.');
+            if (active.playback.state === 'paused' && !options.has('--keep-playing'))
+                finish(await service.control({ type: 'resume' }, false), true);
+            else
+                finish({ ok: true, message: `Kept current station ${active.station.name} (${active.playback.state}).`, status: active }, true);
+            return;
+        }
+        let selection;
+        if (active?.station)
+            selection = { station: active.station, queue: active.queue };
+        else if (query)
+            selection = await resolve(query);
+        else {
+            const source = options.get('--source') ?? (filters.countryCode ? 'country' : 'recent');
+            if (!['recent', 'favorite', 'popular', 'country'].includes(String(source)))
+                throw new Error('--source must be recent, favorites, popular, or country (favorite is also accepted).');
+            if (source === 'country' && !filters.countryCode)
+                throw new Error('Use --country with a two-letter code, for example radiocli play --country JP.');
+            let queue = source === 'favorite' ? state.favorites : source === 'recent' ? state.recent.map(item => item.station) : source === 'country' ? await providers.byCountry(filters.countryCode, 100) : await providers.popular(100);
+            queue = queue.filter(station => matchesFilters(station, filters)).slice(0, filters.limit);
+            if (!queue.length)
+                throw new Error(`No ${source === 'favorite' ? 'favorite' : source} stations match. Start with radiocli play "station name".`);
+            const station = options.has('--pick') ? await select(queue, true) : queue[options.has('--random') ? randomInt(queue.length) : 0];
+            selection = { station, queue };
+        }
+        finish(await service.playStation(selection.station, selection.queue, { openUi: false, ifPlaying: options.has('--keep-playing') ? 'keep' : 'replace' }), true);
+        return;
+    }
+    if (['pause', 'resume', 'stop', 'next', 'previous', 'mute', 'unmute', 'volume'].includes(command)) {
+        if (command === 'volume') {
+            if (words.length !== 1)
+                throw new Error('Usage: radiocli volume <0-100>');
+            finish(await service.control({ type: 'set-volume', volume: integerOption(words[0], 70, 'Volume', 0, 100) }, false));
+        }
+        else {
+            noWords();
+            const control = command === 'mute' || command === 'unmute' ? { type: 'set-muted', muted: command === 'mute' } : { type: command };
+            finish(await service.control(control, false));
+        }
+        return;
+    }
+    if (command === 'search' || command === 'favorites' || command === 'recent') {
+        if (command === 'search' && !query)
+            throw new Error('Usage: radiocli search <query> [--country CODE] [--pick]\nExample: radiocli search jazz --pick');
+        if (command !== 'search')
+            noWords();
+        const stations = command === 'search' ? await providers.search(query, state.settings, filters) : (command === 'favorites' ? state.favorites : state.recent.map(item => item.station)).slice(0, filters.limit);
+        if (options.has('--pick'))
+            finish(await service.playStation(await select(stations, true), stations, { openUi: false }), true);
+        else
+            output.stations(stations, state.favorites, command === 'favorites' ? 'No favorites yet. Tune a station, then run radiocli favorite.' : command === 'recent' ? 'No recent stations yet. Start with radiocli play jazz.' : undefined);
+        return;
+    }
+    if (command === 'countries') {
+        noWords();
+        output.countries(await providers.countries(integerOption(options.get('--limit'), 30, '--limit', 1, 100)));
+        return;
+    }
+    if (command === 'favorite' || command === 'unfavorite') {
+        finish(await service.favoriteStation(query ? (await resolve(query)).station : await currentStation(), command === 'favorite'));
+        return;
+    }
+    if (command === 'preset' || command === 'presets') {
+        if (command === 'presets')
+            noWords();
+        const action = command === 'presets' ? 'list' : words[0] ?? 'list';
+        if (action === 'list') {
+            if (words.length > 1)
+                throw new Error('Usage: radiocli preset list');
+            output.presets(state.presets ?? []);
+        }
+        else if (action === 'save') {
+            const name = words[1];
+            if (!name)
+                throw new Error('Usage: radiocli preset save <name> [station name|provider:id]');
+            // Validate the shortcut before any directory request or selection prompt.
+            if (!/^[a-z0-9][a-z0-9_-]{0,39}$/i.test(name))
+                throw new Error('Preset names must be 1-40 letters, numbers, hyphens, or underscores, starting with a letter or number.');
+            const station = words.length > 2 ? (await resolve(words.slice(2).join(' '))).station : await currentStation();
+            store.savePreset(name, station);
+            finish({ ok: true, message: `Saved preset ${name.toLowerCase()}: ${station.name}. Play it with radiocli play ${name.toLowerCase()}.` });
+        }
+        else if (action === 'remove') {
+            if (words.length !== 2)
+                throw new Error('Usage: radiocli preset remove <name>');
+            store.removePreset(words[1]);
+            finish({ ok: true, message: `Removed preset ${words[1].toLowerCase()}.` });
+        }
+        else
+            throw new Error('Usage: radiocli preset <save|list|remove>. Run radiocli preset --help for examples.');
+        return;
+    }
+    if (command === 'stats') {
+        noWords();
+        output.stats(computeListeningStats(state.activity.sessions));
+    }
+}
+async function readStatus(signal) {
+    const client = await connectRadioSession(undefined, { source: 'cli', signal });
+    return client ? client.status() : null;
+}
+function searchOptions({ options }) {
+    const countryCode = options.get('--country');
+    if (countryCode && (typeof countryCode !== 'string' || !/^[a-z]{2}$/i.test(countryCode)))
+        throw new Error('--country requires a two-letter code, for example US, GB, or JP.');
+    return {
+        limit: integerOption(options.get('--limit'), 20, '--limit', 1, 100),
+        countryCode: typeof countryCode === 'string' ? countryCode.toUpperCase() : undefined,
+        language: options.get('--language'),
+        codec: options.get('--codec'),
+        minBitrate: options.has('--min-bitrate') ? integerOption(options.get('--min-bitrate'), 0, '--min-bitrate', 0, 10000) : undefined
+    };
+}
+function matchesFilters(station, options) {
+    return (!options.countryCode || station.countryCode?.toUpperCase() === options.countryCode)
+        && (!options.language || normalize(station.language ?? '').includes(normalize(options.language)))
+        && (!options.codec || normalize(station.codec ?? '') === normalize(options.codec))
+        && (options.minBitrate === undefined || (station.bitrate ?? 0) >= options.minBitrate);
+}
+function uniqueStations(stations) { return [...new Map(stations.map(station => [stationKey(station), station])).values()]; }
+function normalize(value) { return value.normalize('NFKC').trim().toLowerCase(); }

package/dist/cli/output.js

@@ -0,0 +1,121 @@
+import { stationKey } from '../storage/store.js';
+import { sanitizeTerminalText } from '../safety.js';
+import { resolveTerminalCapabilities } from '../platform/terminal.js';
+import { displayWidth, padDisplayEnd, truncate } from '../ui/format.js';
+import { toAsciiSafe } from '../ui/ascii.js';
+import { themeAccent } from '../ui/theme.js';
+export const clean = (value) => sanitizeTerminalText(value == null ? '' : String(value)) ?? '';
+export class CliOutput {
+    flags;
+    settings;
+    mode;
+    terminal;
+    width;
+    color;
+    constructor(flags, settings, evidence = { isTTY: Boolean(process.stdout.isTTY), columns: process.stdout.columns || 100 }, env = process.env) {
+        this.flags = flags;
+        this.settings = settings;
+        this.mode = flags.json ? 'json' : flags.plain || !evidence.isTTY ? 'plain' : 'human';
+        this.terminal = resolveTerminalCapabilities(env, { isTTY: evidence.isTTY, asciiMode: settings.asciiMode, reduceMotion: settings.reduceMotion });
+        this.width = Math.max(12, evidence.columns - 1);
+        this.color = this.mode === 'human' && evidence.isTTY && !flags.noColor && this.terminal.colorLevel > 0;
+    }
+    text(value) { return this.terminal.unicode ? clean(value) : toAsciiSafe(clean(value)); }
+    heading(value) {
+        return this.accent(this.text(value));
+    }
+    accent(text) {
+        if (!this.color)
+            return text;
+        if (this.terminal.colorLevel < 3)
+            return `\u001b[1m${text}\u001b[0m`;
+        const hex = themeAccent(this.settings.theme).slice(1);
+        const rgb = [0, 2, 4].map(offset => parseInt(hex.slice(offset, offset + 2), 16)).join(';');
+        return `\u001b[1;38;2;${rgb}m${text}\u001b[0m`;
+    }
+    print(value, human, plain = human) {
+        if (this.flags.quiet)
+            return;
+        console.log(this.mode === 'json' ? JSON.stringify(value, null, 2) : this.mode === 'plain' ? plain : human);
+    }
+    stations(stations, favorites, empty = 'No stations found. Try a broader search or remove a filter.', showHint = true) {
+        const favoriteKeys = new Set(favorites.map(stationKey));
+        const rows = stations.map(station => ({ id: stationKey(station), name: station.name, country: station.country ?? '', countryCode: station.countryCode ?? '', codec: station.codec ?? '', bitrate: station.bitrate ?? null, language: station.language ?? '', tags: station.tags, favorite: favoriteKeys.has(stationKey(station)) }));
+        // Preserve the original five-column search TSV contract for existing pipes.
+        const plain = rows.map(row => [row.id, row.name, row.country, row.codec, row.bitrate ?? ''].map(clean).join('\t')).join('\n');
+        const hint = showHint ? '\n\n' + this.text('* Favorite · Tune by name with radiocli play "station name", or add --pick.') : '';
+        const human = stations.length ? this.table(['#', 'STATION', 'COUNTRY', 'QUALITY'], rows.map((row, index) => [String(index + 1), `${row.favorite ? '* ' : ''}${row.name}`, row.country || row.countryCode || '—', [row.codec, row.bitrate ? `${row.bitrate} kbps` : ''].filter(Boolean).join(' ') || '—'])) + hint : this.text(empty);
+        if (!stations.length && this.mode === 'plain') {
+            if (!this.flags.quiet)
+                process.stderr.write(`${this.text(empty)}\n`);
+            return;
+        }
+        this.print(rows, human, plain);
+    }
+    countries(countries) {
+        this.print(countries, countries.length ? this.table(['CODE', 'COUNTRY', 'STATIONS'], countries.map(country => [country.code, country.name, String(country.stationCount)])) : 'No countries found. Try again when the directory is available.', countries.map(country => [country.code, country.stationCount, country.name].map(clean).join('\t')).join('\n'));
+    }
+    now(status) {
+        const fields = this.nowFields(status);
+        this.print(status, this.nowLines(status).map((line, index) => index === 0 ? this.accent(this.fit(line)) : this.fit(line)).join('\n'), Object.entries(fields).map(([key, value]) => `${key}\t${clean(value)}`).join('\n'));
+    }
+    nowLine(status) {
+        return this.text(this.nowLines(status).join(' · '));
+    }
+    result(result, background = false) {
+        const lines = [this.text(result.message)];
+        if (result.status?.persistenceWarning)
+            lines.push(this.text(result.status.persistenceWarning));
+        if (background && result.ok && result.status?.owner === 'headless')
+            lines.push('Playback continues in the background. Use radiocli now or radiocli stop.');
+        this.print(result, lines.join('\n'), `${result.ok ? 'ok' : 'error'}\t${clean(result.message)}`);
+    }
+    presets(presets) {
+        const rows = presets.map(preset => ({ name: preset.name, stationId: stationKey(preset.station), stationName: preset.station.name }));
+        this.print(rows, rows.length ? this.table(['PRESET', 'STATION'], rows.map(row => [row.name, row.stationName])) + '\n\nPlay a preset: radiocli play <name>' : 'No presets yet. Tune a station, then run radiocli preset save work.', rows.map(row => [row.name, row.stationId, row.stationName].map(clean).join('\t')).join('\n'));
+    }
+    stats(stats) {
+        const hours = Math.floor(stats.totalSeconds / 3600);
+        const minutes = Math.floor(stats.totalSeconds % 3600 / 60);
+        const lines = ['Listening stats', `${hours}h ${minutes}m listened · ${stats.sessions} sessions · ${stats.listenedStationCount} stations`, `${stats.currentStreak} day streak · ${stats.longestStreak} day best · ${stats.activeDays} active days`, `Most listened: ${this.text(stats.favoriteStation?.name ?? 'Start listening with radiocli play "station name".')}`];
+        this.print(stats, lines.map((line, index) => index === 0 ? this.heading(this.fit(line)) : this.fit(this.text(line))).join('\n'), Object.entries({ total_seconds: stats.totalSeconds, sessions: stats.sessions, stations: stats.listenedStationCount, current_streak: stats.currentStreak, longest_streak: stats.longestStreak, active_days: stats.activeDays, favorite_station: stats.favoriteStation?.name ?? '' }).map(([key, value]) => `${key}\t${clean(value)}`).join('\n'));
+    }
+    table(headers, rows) {
+        const sanitized = [headers, ...rows].map(row => row.map(value => this.text(value)));
+        const widths = headers.map((_, index) => Math.min(index === 1 ? 44 : 24, Math.max(...sanitized.map(row => displayWidth(row[index] ?? '')))));
+        while (widths.reduce((sum, width) => sum + width, 0) + (widths.length - 1) * 2 > this.width) {
+            const biggest = widths.indexOf(Math.max(...widths));
+            if (widths[biggest] <= 3)
+                break;
+            widths[biggest] = widths[biggest] - 1;
+        }
+        return sanitized.map((row, rowIndex) => {
+            const line = row.map((value, index) => padDisplayEnd(this.fit(value, widths[index]), widths[index])).join('  ').trimEnd();
+            return rowIndex === 0 ? this.accent(this.fit(line)) : this.fit(line);
+        }).join('\n');
+    }
+    fit(value, width = this.width) {
+        const result = truncate(value, width);
+        return this.terminal.unicode ? result : toAsciiSafe(result);
+    }
+    nowFields(status) {
+        return {
+            state: status?.playback.state ?? 'idle', station_id: status?.station ? stationKey(status.station) : '',
+            station: status?.station?.name ?? '', track: status?.nowPlaying?.title ?? '',
+            output: status?.playback.airPlayDeviceName ?? (status?.playback.backend === 'airplay' ? 'AirPlay' : 'Local speakers'),
+            volume: status?.playback.volume ?? this.settings.volume, muted: status?.playback.muted ?? false,
+            backend: status?.playback.backend ?? 'none', warning: status?.persistenceWarning ?? ''
+        };
+    }
+    nowLines(status) {
+        if (!status?.station)
+            return ['No station is playing. Start with radiocli play "station name".'];
+        const fields = this.nowFields(status);
+        const lines = [`${fields.station} · ${fields.state[0].toUpperCase()}${fields.state.slice(1)}`, fields.track || 'Track metadata unavailable', `${fields.output} · ${fields.backend} · Volume ${fields.volume}%${fields.muted ? ' (muted)' : ''}`];
+        if (status.playback.message && clean(status.playback.message) !== clean(status.station.name))
+            lines.push(status.playback.message);
+        if (status.persistenceWarning)
+            lines.push(status.persistenceWarning);
+        return lines.map(line => this.text(line));
+    }
+}