@ciphore/radiocli 0.2.4 → 0.2.6

package/dist/cli/render-tui.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export async function renderTui(printHelp, encodedCommand) {
+    if (!process.stdin.isTTY) {
+        console.error('The interactive TUI needs terminal input. Use radiocli commands in a headless session, or connect with a terminal (for example, ssh -t).');
+        printHelp();
+        process.exitCode = 1;
+        return;
+    }
+    const { configureTerminalRenderer } = await import('../ui/terminal-renderer.js');
+    const terminal = await configureTerminalRenderer(process.env, { isTTY: Boolean(process.stdout.isTTY), colorDepth: process.stdout.getColorDepth?.() });
+    const { rtlSafeOutput } = await import('../ui/rtl-output.js');
+    const [{ render }, { App }, { decodeAgentCommand }, { openTuiSession }] = await Promise.all([import('ink'), import('../ui/App.js'), import('../agent/service.js'), import('../agent/tui-session.js')]);
+    const initialAgentCommand = encodedCommand ? decodeAgentCommand(encodedCommand) : undefined;
+    const { session: playbackSession, warning: playbackRecoveryWarning } = await openTuiSession();
+    try {
+        const app = render(_jsx(App, { playbackSession: playbackSession, playbackRecoveryWarning: playbackRecoveryWarning, initialAgentCommand: initialAgentCommand }), {
+            stdout: terminal.interactive && process.stdout.isTTY && !terminal.screenReader ? rtlSafeOutput(process.stdout) : process.stdout,
+            // App owns Ctrl+C so it can confirm before performing a clean shutdown.
+            exitOnCtrlC: false,
+            isScreenReaderEnabled: terminal.screenReader,
+            interactive: terminal.interactive ? undefined : false,
+            debug: !terminal.interactive,
+            kittyKeyboard: { mode: terminal.interactive ? 'auto' : 'disabled', flags: ['disambiguateEscapeCodes', 'reportEventTypes', 'reportAllKeysAsEscapeCodes'] }
+        });
+        await app.waitUntilExit();
+    }
+    catch (error) {
+        playbackSession?.disconnect();
+        if (playbackSession)
+            console.error('The TUI closed unexpectedly. Playback continues; reopen radiocli to reconnect, or run radiocli stop.');
+        throw error;
+    }
+    await playbackSession?.close();
+}

package/dist/cli.js

@@ -1,38 +1,19 @@
 #!/usr/bin/env node
-import { jsx as _jsx } from "react/jsx-runtime";
-import { realpathSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { ProviderManager } from './providers/provider-manager.js';
-import { PlayerController } from './player/player-controller.js';
-import { defaultLibraryPath, JsonLibraryStore } from './storage/store.js';
-import { parsePlaylistFile, writeM3u } from './playlists/playlist.js';
-import { importStreamUrl } from './streams/import-stream.js';
-import { detectPlaybackBackends, playbackBackendStatusLines } from './player/backend-install.js';
-import { resolveCommand } from './platform/executables.js';
-import { diagnoseCommand } from './player/command-diagnostics.js';
-import { airPlaySenderHealth } from './player/airplay-sender-health.js';
 import { appVersion } from './version.js';
-import { checkForUpdate, installUpdate, updateCommandForInstall } from './update-check.js';
-import { runAlarmCommand } from './alarms/cli.js';
-import { createSchedulerAdapter } from './alarms/scheduler.js';
-import { runSetup } from './setup.js';
-import { runAgentCliCommand, runMcpCommand } from './agent/cli.js';
-import { decodeAgentCommand } from './agent/service.js';
-import { runHeadlessAgentHost } from './agent/headless-host.js';
-import { configureMcpIntegrations } from './agent/mcp-install.js';
-import { defaultAgentControlSettings } from './types.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';
+import { completionCandidates, isListenerCommand, listenerCommands, listenerHelp } from './cli/arguments.js';
+import { sanitizeTerminalText } from './safety.js';
 const runtime = { nodePath: process.execPath, cliPath: fileURLToPath(import.meta.url) };
 if (isDirectRun(process.argv[1], import.meta.url)) {
     const args = process.argv.slice(2);
+    process.stdout.on('error', error => {
+        if (error.code === 'EPIPE')
+            process.exit(0);
+        else
+            throw error;
+    });
     if (args[0] === 'agent-ui') {
         const encoded = args[1];
         if (!encoded)
@@ -40,12 +21,14 @@ if (isDirectRun(process.argv[1], import.meta.url)) {
         await renderTui(encoded);
     }
     else if (args[0] === 'agent-host') {
+        const { runHeadlessAgentHost } = await import('./agent/headless-host.js');
         await runHeadlessAgentHost();
     }
     else if (args.length > 0) {
         await runCommand(args).catch(error => {
-            console.error(error instanceof Error ? error.message : String(error));
-            process.exitCode = 1;
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(message.split('\n').map(line => sanitizeTerminalText(line) ?? '').join('\n'));
+            process.exitCode = error instanceof Error && error.name === 'AbortError' ? 130 : 1;
         });
     }
     else {
@@ -53,83 +36,119 @@ if (isDirectRun(process.argv[1], import.meta.url)) {
     }
 }
 async function renderTui(encodedCommand) {
-    if (!process.stdin.isTTY) {
-        console.error('The interactive TUI needs terminal input. Use radiocli commands in a headless session, or connect with a terminal (for example, ssh -t).');
-        printHelp();
-        process.exitCode = 1;
-        return;
-    }
-    const { configureTerminalRenderer } = await import('./ui/terminal-renderer.js');
-    const terminal = await configureTerminalRenderer(process.env, { isTTY: Boolean(process.stdout.isTTY), colorDepth: process.stdout.getColorDepth?.() });
-    const [{ render }, { App }] = await Promise.all([import('ink'), import('./ui/App.js')]);
-    render(_jsx(App, { initialAgentCommand: encodedCommand ? decodeAgentCommand(encodedCommand) : undefined }), {
-        // App owns Ctrl+C so it can confirm before performing a clean shutdown.
-        exitOnCtrlC: false,
-        isScreenReaderEnabled: terminal.screenReader,
-        interactive: terminal.interactive ? undefined : false,
-        debug: !terminal.interactive,
-        kittyKeyboard: { mode: terminal.interactive ? 'auto' : 'disabled', flags: ['disambiguateEscapeCodes', 'reportEventTypes', 'reportAllKeysAsEscapeCodes'] }
-    });
+    // React's development profiler retains per-frame timing entries in Node.
+    // Choose the production runtime before loading Ink or JSX; explicit developer
+    // environments still take precedence.
+    process.env.NODE_ENV ??= 'production';
+    const { renderTui: render } = await import('./cli/render-tui.js');
+    await render(printHelp, encodedCommand);
 }
 export async function runCommand(args) {
     const [command, ...rest] = args;
     if (!command || command === 'help' || command === '--help' || command === '-h') {
-        printHelp();
+        if (command === 'help' && rest[0] && rest[0] !== '--all') {
+            await runCommand([rest[0], '--help']);
+            return;
+        }
+        printHelp(rest.includes('--all'));
         return;
     }
     if (command === 'version' || command === '--version' || command === '-v') {
         console.log(appVersion());
         return;
     }
+    if (command === '_complete') {
+        let presets = [];
+        if (rest.length > 1 && ['play', 'favorite', 'unfavorite', 'preset'].includes(rest[0])) {
+            try {
+                // Completion is read-only, including when a library needs repair.
+                const { defaultLibraryPath } = await import('./storage/store.js');
+                const library = JSON.parse(readFileSync(defaultLibraryPath(), 'utf8'));
+                if (Array.isArray(library.presets))
+                    presets = library.presets.flatMap(preset => typeof preset?.name === 'string' && /^[a-z0-9][a-z0-9_-]{0,39}$/.test(preset.name) ? [preset.name] : []);
+            }
+            catch { /* Completion must remain quiet when storage is unavailable. */ }
+        }
+        const candidates = completionCandidates(rest, presets);
+        if (candidates.length)
+            console.log(candidates.join('\n'));
+        return;
+    }
+    const optionArgs = rest.includes('--') ? rest.slice(0, rest.indexOf('--')) : rest;
+    const wantsHelp = optionArgs.includes('--help') || optionArgs.includes('-h');
+    if (isListenerCommand(command)) {
+        if (wantsHelp)
+            console.log(listenerHelp(command));
+        else {
+            const { runListenerCommand } = await import('./cli/listener.js');
+            await runListenerCommand(command, rest, runtime);
+        }
+        return;
+    }
+    if (command === 'agent' && wantsHelp) {
+        const { agentCommandUsage } = await import('./agent/cli.js');
+        console.log(`${agentCommandUsage()}\nJSON controls for local agents. Everyday listening is available directly: radiocli play, now, favorites.`);
+        return;
+    }
+    const commandHelp = legacyCommandHelp()[command];
+    if (wantsHelp && commandHelp) {
+        console.log(commandHelp);
+        return;
+    }
     if (command === 'alarm') {
+        const { runAlarmCommand } = await import('./alarms/cli.js');
         await runAlarmCommand(rest);
         return;
     }
     if (command === 'mcp') {
+        const { runMcpCommand } = await import('./agent/cli.js');
         await runMcpCommand(rest, runtime);
         return;
     }
     if (command === 'agent') {
+        const { runAgentCliCommand } = await import('./agent/cli.js');
         await runAgentCliCommand(rest, runtime);
         return;
     }
     if (command === 'setup') {
         if (rest.includes('--help') || rest.includes('-h')) {
-            printSetupHelp();
+            await printSetupHelp();
             return;
         }
+        const { runSetup } = await import('./setup.js');
         await runSetup({ args: rest });
         return;
     }
+    if (command === 'media-controls') {
+        if (rest.length > 1 || rest[0] !== undefined && !['auto', 'on', 'off'].includes(rest[0])) {
+            throw new Error('Usage: radiocli media-controls [auto|on|off]');
+        }
+        const [{ JsonLibraryStore }, { desktopMediaPolicy }] = await Promise.all([import('./storage/store.js'), import('./platform/desktop-media.js')]);
+        const store = new JsonLibraryStore();
+        if (rest[0])
+            store.updateSettings({ desktopMediaControls: rest[0] });
+        const policy = desktopMediaPolicy(store.snapshot().settings);
+        console.log(`desktop_media_preference=${store.snapshot().settings.desktopMediaControls ?? 'auto'}`);
+        console.log(`desktop_media_effective=${policy.preference} ${policy.enabled ? 'enabled' : 'disabled'}`);
+        console.log(`desktop_media_note=${policy.reason}`);
+        if (rest[0])
+            console.log('Restart active RadioCLI sessions to apply this preference. RADIOCLI_DESKTOP_MEDIA=off overrides the saved preference.');
+        return;
+    }
     if (!isKnownCommand(command)) {
-        throw new Error(`Unknown command: ${command}\nRun radiocli help.`);
+        const suggestion = suggestCommand(command);
+        throw new Error(`Unknown command: ${command}${suggestion ? `\nDid you mean radiocli ${suggestion}?` : ''}\nRun radiocli help.`);
     }
     if (command === 'doctor') {
-        const backends = detectPlaybackBackends();
-        const mpvDiagnostic = diagnoseCommand('mpv');
-        const report = await doctorReport(backends, mpvDiagnostic);
-        if (rest.includes('--json')) {
-            console.log(JSON.stringify(report, null, 2));
-            return;
-        }
-        console.log(`backends=${backends.join(',') || 'none'}`);
-        printMpvDiagnostic(mpvDiagnostic);
-        printPlaybackBackendStatus(backends);
-        for (const [name, capability] of Object.entries(report.capabilities)) {
-            console.log(`capability_${name}=${capability.status} ${capability.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}`);
+        const { runDoctor } = await import('./cli/doctor.js');
+        await runDoctor(rest);
         return;
     }
     if (command === 'update') {
         const unknown = rest.filter(arg => arg !== '--install');
         if (unknown.length > 0)
             throw new Error('Usage: radiocli update [--install]');
+        const { checkForUpdate, installUpdate, updateCommandForInstall } = await import('./update-check.js');
         const updateCheck = await checkForUpdate();
         const updateCommand = updateCommandForInstall();
         if (updateCheck.error) {
@@ -146,9 +165,11 @@ export async function runCommand(args) {
             if (!result.ok)
                 throw new Error(`Update install failed. Run manually: ${result.command}${result.output ? `\n${result.output}` : ''}`);
             console.log('updated=yes');
+            const [{ JsonLibraryStore }, { defaultAgentControlSettings }] = await Promise.all([import('./storage/store.js'), import('./types.js')]);
             const agentControl = new JsonLibraryStore().snapshot().settings.agentControl ?? defaultAgentControlSettings;
             if (agentControl.enabled) {
                 try {
+                    const { configureMcpIntegrations } = await import('./agent/mcp-install.js');
                     const repaired = await configureMcpIntegrations(true, runtime);
                     const failed = repaired.filter(item => item.status === 'failed');
                     console.log(`mcp_repaired=${failed.length ? 'partial' : 'yes'}`);
@@ -164,6 +185,9 @@ export async function runCommand(args) {
         return;
     }
     if (command === 'check') {
+        const [{ JsonLibraryStore }, { ProviderManager }, { PlayerController }, { playbackBackendStatusLines }] = await Promise.all([
+            import('./storage/store.js'), import('./providers/provider-manager.js'), import('./player/player-controller.js'), import('./player/backend-install.js')
+        ]);
         const store = new JsonLibraryStore();
         const providers = new ProviderManager();
         const player = new PlayerController(() => store.snapshot().settings);
@@ -171,40 +195,22 @@ export async function runCommand(args) {
         const health = await providers.health(store.snapshot().settings);
         console.log(`store=${store.filePath}`);
         console.log(`backends=${backends.join(',') || 'none'}`);
-        printPlaybackBackendStatus(backends);
+        for (const line of playbackBackendStatusLines(backends))
+            console.log(line);
         for (const [provider, status] of Object.entries(health)) {
             console.log(`${provider}=${status}`);
         }
         return;
     }
-    if (command === 'countries') {
-        const providers = new ProviderManager();
-        const countries = await providers.countries(30);
-        for (const country of countries) {
-            console.log(`${country.code}\t${country.stationCount}\t${country.name}`);
-        }
-        return;
-    }
-    if (command === 'search') {
-        const query = rest.join(' ').trim();
-        if (!query) {
-            throw new Error('Usage: radiocli search <query>');
-        }
-        const store = new JsonLibraryStore();
-        const providers = new ProviderManager();
-        const stations = await providers.search(query, store.snapshot().settings, { limit: 20 });
-        for (const station of stations) {
-            console.log(`${station.provider}:${station.id}\t${station.name}\t${station.country ?? ''}\t${station.codec ?? ''}\t${station.bitrate ?? ''}`);
-        }
-        return;
-    }
     if (command === 'import') {
         const target = rest[0];
         if (!target) {
             throw new Error('Usage: radiocli import <stream-url|playlist.m3u|playlist.pls|playlist.xspf> [station name]');
         }
+        const { JsonLibraryStore } = await import('./storage/store.js');
         const store = new JsonLibraryStore();
         if (/^https?:\/\//i.test(target)) {
+            const { importStreamUrl } = await import('./streams/import-stream.js');
             const result = await importStreamUrl(target, rest.slice(1).join(' ') || undefined);
             store.addImported([result.station]);
             console.log(`imported=${result.station.name}`);
@@ -212,12 +218,14 @@ export async function runCommand(args) {
                 console.log(`warning=${result.warning}`);
             return;
         }
+        const { parsePlaylistFile } = await import('./playlists/playlist.js');
         const stations = parsePlaylistFile(target);
         store.addImported(stations);
         console.log(`imported=${stations.length}`);
         return;
     }
     if (command === 'export') {
+        const [{ JsonLibraryStore }, { writeM3u }] = await Promise.all([import('./storage/store.js'), import('./playlists/playlist.js')]);
         const file = rest[0] ?? 'radiocli-favorites.m3u';
         const store = new JsonLibraryStore();
         const state = store.snapshot();
@@ -226,25 +234,90 @@ export async function runCommand(args) {
         return;
     }
 }
-export function printHelp() {
+export function printHelp(all = false) {
     console.log(`RadioCLI
 
-Usage:
-  radiocli                 Start the TUI
-  radiocli version         Print the installed version
-  radiocli check           Show provider/backend health
-  radiocli doctor [--json] Show local playback setup guidance
-  radiocli setup           Install and verify native playback tools
-  radiocli mcp <command>   Install, inspect, or run the MCP integration
-  radiocli agent <command> Scriptable radio controls for local agents
-  radiocli update          Show update availability and install command
-  radiocli update --install Install the latest release and repair enabled MCP entries
-  radiocli countries       Print top countries
-  radiocli search <query>  Search public stations
+Usage: radiocli [command]
+  Run radiocli without a command to open the TUI.
+
+Everyday listening:
+  radiocli play [station] Start or continue listening; names and presets work
+  radiocli pause          Pause; use play to continue
+  radiocli next           Tune the next station in the current queue
+  radiocli now            See the current station, track, and volume
+  radiocli volume <0-100> Set listening volume
+  radiocli favorite       Save the current station
+  radiocli favorites      List saved stations; add --pick to choose one
+  radiocli stop           Stop playback and close the background player
+${all ? `
+More listening controls:
+  radiocli previous       Tune the previous station in the queue
+  radiocli resume         Resume paused playback (play also works)
+  radiocli mute | unmute  Mute or restore sound
+  radiocli now --watch    Watch station and track changes
+  radiocli status         Alias for now
+  radiocli play --favorites | --recent | --popular
+                         Choose a queue; add --random or --pick
+
+Discovery and library:
+  radiocli search <query> Search stations; --country, --limit, --pick
+  radiocli countries      List top countries
+  radiocli recent         List recently played stations
+  radiocli unfavorite     Remove a favorite (current station by default)
+  radiocli preset save <name>   Save a shortcut; play with play <name>
+  radiocli preset remove <name> Remove a shortcut
+  radiocli presets        List shortcuts; also: preset list
+  radiocli stats          Show listening time and streaks
   radiocli import <target> Import a stream URL or local playlist
-  radiocli export [file]   Export favorites/imports as .m3u
+  radiocli export [file]  Export favorites/imports as .m3u
   radiocli alarm <command> Manage alarms and scheduled radio
-`);
+
+Setup and integrations:
+  radiocli setup          Install and verify native playback tools
+  radiocli doctor [--json] Show local playback setup guidance
+  radiocli check          Show provider/backend health
+  radiocli version        Print the installed version
+  radiocli update         Check for updates; --install to install
+  radiocli media-controls [auto|on|off] Configure Linux desktop media controls
+  radiocli mcp <command>  Install, inspect, or run the MCP integration
+  radiocli agent <command> Scriptable radio controls for local agents
+` : ''}
+Examples:
+  radiocli play jazz               Find a station and listen
+  radiocli play                    Continue the current or last station
+  radiocli play --favorites        Listen from your favorites
+
+More help:
+  radiocli help --all              Browse every command by category
+  radiocli help play               Options and examples for one command
+  radiocli completion <shell>      Print a Tab completion script
+${all ? '\nListener commands support --json, --plain, --quiet, and --no-input.\nUse radiocli <command> --help for options and examples.\n' : ''}
+`.trimEnd());
+}
+function legacyCommandHelp() {
+    return {
+        check: 'Usage: radiocli check\nShow local store paths, playback backends, and provider health.',
+        doctor: 'Usage: radiocli doctor [--json] [--playback]\nCheck playback tools without changing settings. Add --playback to rehearse local WAV playback through null/dummy audio.',
+        update: 'Usage: radiocli update [--install]\nCheck for updates. Add --install to install and repair enabled MCP entries.',
+        import: 'Usage: radiocli import <stream-url|playlist.m3u|playlist.pls|playlist.xspf> [station name]\nExample: radiocli import https://example.com/live.mp3 "Example FM"',
+        export: 'Usage: radiocli export [file]\nExport favorites and imports as M3U (default: radiocli-favorites.m3u).',
+        'media-controls': 'Usage: radiocli media-controls [auto|on|off]\nInspect or configure Linux desktop media controls.',
+        mcp: 'Usage: radiocli mcp <enable|install|repair|disable|status|config|serve>\nManage the optional local agent integration.'
+    };
+}
+function suggestCommand(input) {
+    const candidates = [...listenerCommands, ...Object.keys(legacyCommandHelp()), 'setup', 'alarm', 'agent', 'help', 'version'];
+    const distance = (word) => {
+        let row = Array.from({ length: word.length + 1 }, (_, index) => index);
+        for (let i = 1; i <= input.length; i += 1) {
+            const next = [i];
+            for (let j = 1; j <= word.length; j += 1)
+                next[j] = Math.min(next[j - 1] + 1, row[j] + 1, row[j - 1] + (input[i - 1] === word[j - 1] ? 0 : 1));
+            row = next;
+        }
+        return row[word.length];
+    };
+    return candidates.map(word => ({ word, distance: distance(word) })).filter(item => item.distance <= (input.length > 3 ? 2 : 1)).sort((a, b) => a.distance - b.distance)[0]?.word;
 }
 export function isDirectRun(entryPath, moduleUrl) {
     if (!entryPath) {
@@ -260,7 +333,8 @@ export function isDirectRun(entryPath, moduleUrl) {
 function isKnownCommand(command) {
     return ['check', 'doctor', 'setup', 'update', 'countries', 'search', 'import', 'export', 'alarm', 'mcp', 'agent'].includes(command);
 }
-function printSetupHelp() {
+async function printSetupHelp() {
+    const { isAirPlayPlatformSupported } = await import('./player/airplay-policy.js');
     console.log(`RadioCLI Setup
 
 Usage:
@@ -273,100 +347,9 @@ Usage:
   radiocli setup --mcp --agent-ui        Open a terminal TUI for agent playback (default)
   radiocli setup --mcp --headless-agent  Opt out of external terminal windows
   radiocli setup --no-mcp                Disable and remove agent MCP entries
-  radiocli setup --package-manager <pm>  Use brew, winget, scoop, choco,
+${process.platform === 'linux' && isAirPlayPlatformSupported() ? '  radiocli setup --airplay               Enable experimental Linux AirPlay and set up prerequisites\n  radiocli setup --no-airplay            Disable Linux AirPlay; keep shared services and packages\n' : ''}  radiocli setup --package-manager <pm>  Use brew, winget, scoop, choco,
                                          apt, dnf, pacman, apk, zypper,
                                          pkg (FreeBSD), pkg_add, pkgin,
                                          termux-pkg (Termux), or pkgman (Haiku)
 `);
 }
-function printPlaybackBackendStatus(backends) {
-    for (const line of playbackBackendStatusLines(backends)) {
-        console.log(line);
-    }
-}
-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 terminal = resolveTerminalCapabilities(process.env, { isTTY: Boolean(process.stdout.isTTY), colorDepth: process.stdout.getColorDepth?.() });
-    let scheduler;
-    try {
-        const adapter = createSchedulerAdapter();
-        scheduler = await adapter.probeCapabilities?.();
-    }
-    catch {
-        scheduler = { supported: false, exactWake: false, catchUpAfterWake: false, message: 'The optional scheduler probe failed. Run radiocli alarm doctor for repair guidance.' };
-    }
-    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
-    });
-    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,
-        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
-        },
-        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) {
-    return { ...diagnostic, path: redactHome(diagnostic.path) };
-}
-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/platform/capabilities.js

@@ -48,6 +48,13 @@ export function platformCapabilities(host, evidence) {
         unicode: evidence.unicode === false ? unavailable('ASCII decoration mode is selected; international station data is preserved.') : available('Unicode decoration is enabled; terminal font coverage determines glyph appearance.'),
         color: evidence.color === false ? unavailable('Color is disabled for the terminal or by user preference.') : available('Color is enabled at the terminal supported depth.'),
         screenReader: available(evidence.screenReader ? 'Screen-reader mode is enabled; decorative animation is disabled.' : 'Screen-reader mode is available through INK_SCREEN_READER=true.'),
-        airPlay: adapters.airPlay && evidence.backends.includes('airplay') ? available('Experimental macOS output; receiver selection and worker readiness are still required.', 'airplay') : unavailable(adapters.airPlay ? 'Experimental AirPlay requires FFmpeg, Bonjour, and the safe optional sender.' : 'AirPlay output is available only on macOS.')
+        airPlay: !adapters.airPlay ? unavailable('Experimental AirPlay is supported on macOS and native Linux; this environment is not supported.')
+            : evidence.airPlay ? evidence.airPlay.ready
+                ? evidence.airPlay.discoveryService === 'unverified' ? unverified(evidence.airPlay.message, 'airplay') : available(evidence.airPlay.message, 'airplay')
+                : unavailable(evidence.airPlay.message)
+                : evidence.backends.includes('airplay')
+                    ? host.id === 'linux' ? unverified('Experimental Linux output requires an explicit discovery-service and native-sender check. Select a receiver each session.', 'airplay')
+                        : available('Experimental macOS output; receiver selection and worker readiness are still required.', 'airplay')
+                    : unavailable(`Experimental AirPlay requires FFmpeg, ${host.id === 'linux' ? 'Avahi' : 'Bonjour'}, and the safe optional sender.`)
     };
 }

package/dist/platform/desktop-media.js

@@ -0,0 +1,61 @@
+import { resolve } from 'node:path';
+import { planMpvDesktopMedia } from '../player/mpv-desktop-media.js';
+import { identifyOmarchy } from './omarchy.js';
+import { sessionBusSocket, startMpris } from './mpris.js';
+import { resolveCommandDetails } from './executables.js';
+export function desktopMediaPolicy(settings, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const override = env.RADIOCLI_DESKTOP_MEDIA;
+    const preference = override === 'auto' || override === 'on' || override === 'off' ? override : settings.desktopMediaControls ?? 'auto';
+    const disabled = (reason) => ({ enabled: false, preference, reason, mpvArgs: [] });
+    if (preference === 'off')
+        return disabled('Desktop media controls are disabled.');
+    if (platform !== 'linux')
+        return disabled('Desktop media controls currently require Linux.');
+    if (!sessionBusSocket(env.DBUS_SESSION_BUS_ADDRESS ?? ''))
+        return disabled('A local Unix session bus is required.');
+    if (preference === 'auto') {
+        const profile = (options.omarchy ?? (() => identifyOmarchy({ platform, env })))();
+        if (profile.kind !== 'quattro' || profile.source !== 'package' || !profile.session.localDesktop)
+            return disabled('Automatic desktop media controls require a packaged Omarchy Quattro local desktop.');
+    }
+    const mpv = (options.mpv ?? (() => planMpvDesktopMedia({ platform, env, executable: resolveCommandDetails('mpv', { platform, env }).path })))();
+    if (mpv.status !== 'compatible')
+        return disabled(mpv.reason);
+    return { enabled: true, preference, reason: mpv.reason, mpvArgs: mpv.args };
+}
+/** State and ICY updates reuse the owning player's event stream. No additional
+ * playback polling is needed and the bridge never connects through MCP. */
+export function startDesktopMediaControls(options) {
+    if (!options.policy.enabled)
+        return { refresh() { }, close() { } };
+    let title;
+    let previousStream;
+    let previousStation;
+    let disposed = false;
+    const bridge = startMpris({
+        identity: resolve(options.identity),
+        address: (options.env ?? process.env).DBUS_SESSION_BUS_ADDRESS ?? '',
+        command: command => options.command(command, () => !disposed),
+        snapshot: () => ({ ...options.status(), title, available: !options.suspended() && options.player.desktopMediaCompatible() })
+    });
+    const refresh = () => {
+        const station = options.status().station;
+        const key = station ? `${station.provider}\0${station.id}` : undefined;
+        if (key !== previousStation) {
+            title = undefined;
+            previousStation = key;
+        }
+        bridge.refresh();
+    };
+    const removeState = options.player.onChange(state => {
+        if (state.streamUrl !== previousStream) {
+            title = undefined;
+            previousStream = state.streamUrl;
+        }
+        refresh();
+    });
+    const removeMetadata = options.player.onMetadata(metadata => { title = metadata.title; refresh(); });
+    return { refresh, close() { disposed = true; removeState(); removeMetadata(); bridge.close(); } };
+}