@ciphore/radiocli 0.2.3 → 0.2.5

package/dist/cli.js

@@ -1,108 +1,150 @@
 #!/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 { JsonLibraryStore } from './storage/store.js';
-import { parsePlaylistFile, stationFromUrl, writeM3u } from './playlists/playlist.js';
-import { detectPlaybackBackends, playbackBackendStatusLines } from './player/backend-install.js';
-import { resolveCommand } from './player/command.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 { 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 { 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)
             throw new Error('Missing RadioCLI agent startup request.');
-        const [{ render }, { App }] = await Promise.all([import('ink'), import('./ui/App.js')]);
-        render(_jsx(App, { initialAgentCommand: decodeAgentCommand(encoded) }), {
-            exitOnCtrlC: false,
-            kittyKeyboard: { mode: 'auto', flags: ['disambiguateEscapeCodes', 'reportEventTypes', 'reportAllKeysAsEscapeCodes'] }
-        });
+        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 {
-        const [{ render }, { App }] = await Promise.all([import('ink'), import('./ui/App.js')]);
-        render(_jsx(App, {}), {
-            // App owns Ctrl+C so it can confirm before performing a clean shutdown.
-            exitOnCtrlC: false,
-            kittyKeyboard: {
-                mode: 'auto',
-                flags: ['disambiguateEscapeCodes', 'reportEventTypes', 'reportAllKeysAsEscapeCodes']
-            }
-        });
+        await renderTui();
     }
 }
+async function renderTui(encodedCommand) {
+    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');
-        if (rest.includes('--json')) {
-            console.log(JSON.stringify(doctorReport(backends, mpvDiagnostic), null, 2));
-            return;
-        }
-        console.log(`backends=${backends.join(',') || 'none'}`);
-        printMpvDiagnostic(mpvDiagnostic);
-        printPlaybackBackendStatus(backends);
+        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) {
@@ -119,9 +161,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'}`);
@@ -137,6 +181,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);
@@ -144,45 +191,37 @@ 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 file = rest[0];
-        if (!file) {
-            throw new Error('Usage: radiocli import <playlist.m3u|playlist.pls|playlist.xspf>');
+        const target = rest[0];
+        if (!target) {
+            throw new Error('Usage: radiocli import <stream-url|playlist.m3u|playlist.pls|playlist.xspf> [station name]');
         }
-        const stations = parsePlaylistFile(file);
+        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}`);
+            if (result.warning)
+                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();
@@ -190,38 +229,91 @@ export async function runCommand(args) {
         console.log(`exported=${file}`);
         return;
     }
-    if (command === 'add-url') {
-        const url = rest[0];
-        if (!url || !/^https?:\/\//i.test(url)) {
-            throw new Error('Usage: radiocli add-url <stream-url> [station name]');
-        }
-        const station = stationFromUrl(url, rest.slice(1).join(' ') || url);
-        const store = new JsonLibraryStore();
-        store.addImported([station]);
-        console.log(`added=${station.name}`);
-        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
+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 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 setup           Install and verify native playback tools
-  radiocli mcp <command>   Install, inspect, or run the MCP integration
+  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
-  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
-  radiocli import <file>   Import .m3u, .pls, or .xspf streams
-  radiocli export [file]   Export favorites/imports as .m3u
-  radiocli add-url <url> [name]
-  radiocli alarm <command> Manage alarms and scheduled radio
-`);
+` : ''}
+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) {
@@ -235,9 +327,10 @@ export function isDirectRun(entryPath, moduleUrl) {
     }
 }
 function isKnownCommand(command) {
-    return ['check', 'doctor', 'setup', 'update', 'countries', 'search', 'import', 'export', 'add-url', 'alarm', 'mcp', 'agent'].includes(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:
@@ -250,58 +343,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,
-                                         apt, dnf, pacman, apk, or zypper
+${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);
-    }
-}
-function doctorReport(backends, mpvDiagnostic) {
-    const commands = Object.fromEntries(['mpv', 'ffplay', 'vlc', 'cvlc', 'ffmpeg', 'dns-sd'].map(command => [command, redactHome(resolveCommand(command))]));
-    const airPlay = airPlaySenderHealth();
-    return {
-        radioCliVersion: appVersion(),
-        nodeVersion: process.version,
-        platform: process.platform,
-        architecture: process.arch,
-        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 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

@@ -0,0 +1,60 @@
+import { browserCommands, clipboardCandidates } from './desktop.js';
+import { nativeAdapters } from './runtime.js';
+const available = (message, adapter) => ({ status: 'available', message, ...(adapter ? { adapter } : {}) });
+const unavailable = (message) => ({ status: 'unavailable', message });
+const unverified = (message, adapter) => ({ status: 'unverified', message, ...(adapter ? { adapter } : {}) });
+/**
+ * Availability is independent per feature. Tool discovery never substitutes for
+ * desktop, scheduler, audio-device, permission, or upstream runtime verification.
+ */
+export function platformCapabilities(host, evidence) {
+    const adapters = nativeAdapters(host);
+    const commands = new Set(evidence.commands);
+    const has = (name) => commands.has(name);
+    const backend = ['mpv', 'ffplay', 'vlc', 'airplay'].find(name => evidence.backends.includes(name));
+    const desktop = evidence.graphicalSession;
+    const opener = browserCommands(host).find(item => has(item.command));
+    const clipboard = clipboardCandidates(host).find(item => has(item.command));
+    const schedulerTool = adapters.scheduler === 'launchd' ? 'launchctl'
+        : adapters.scheduler === 'task-scheduler' ? 'schtasks.exe' : adapters.scheduler === 'systemd' ? 'systemctl' : null;
+    const backgroundScheduling = evidence.scheduler
+        ? evidence.scheduler.supported ? available(evidence.scheduler.message, adapters.scheduler ?? undefined) : unavailable(evidence.scheduler.message)
+        : schedulerTool && has(schedulerTool) ? unverified('Native scheduler command found; verify the per-user session with radiocli alarm doctor.', adapters.scheduler ?? undefined)
+            : unavailable(adapters.scheduler ? `The ${schedulerTool} scheduler command is unavailable.` : `Reliable background scheduling has no verified adapter on ${host.id}.`);
+    const sleepTool = adapters.inhibitor === 'caffeinate' ? 'caffeinate' : adapters.inhibitor === 'logind' ? 'systemd-inhibit' : adapters.inhibitor === 'windows' ? 'powershell.exe' : null;
+    const volumeTool = adapters.volume === 'macos' ? has('osascript') ? 'osascript' : null
+        : adapters.volume === 'windows' ? ['powershell.exe', 'pwsh.exe'].find(has)
+            : adapters.volume === 'unix-audio' ? ['wpctl', 'pactl', 'amixer'].find(has) : null;
+    const storage = evidence.storageWritable === true ? available('The local data directory is writable; operations still verify each write.')
+        : evidence.storageWritable === false ? unavailable('Local data is not writable. Set RADIOCLI_HOME to a private writable directory; existing readable data can still be inspected.')
+            : unverified('Local JSON data uses the existing private user paths; writability is checked when used.');
+    return {
+        playback: backend ? available(`${backend} executable detected; stream and audio-device readiness are checked when tuning.`, backend) : unavailable('No playback backend detected. Run radiocli setup or configure a native player path.'),
+        playbackControls: backend === 'mpv' ? available('mpv IPC provides pause, mute, volume, metadata, and media keys.', 'mpv')
+            : unavailable(backend === 'airplay' ? 'AirPlay provides volume and mute; pause and media-key playback controls require local mpv.' : 'Pause, mute, volume, metadata, and media-key playback controls require mpv.'),
+        packageInstallation: evidence.packageManager ? available('Explicit setup plans require confirmation or --yes; --dry-run never installs.', evidence.packageManager) : unavailable('No supported package manager detected; install playback prerequisites manually.'),
+        storage,
+        filePermissions: adapters.posixPermissions ? available('Private files use mode 0600 and private directories use mode 0700; the filesystem must enforce POSIX permissions.') : available('Private user directories inherit Windows ACLs; POSIX modes do not configure Windows ACLs.'),
+        atomicWrites: evidence.storageWritable === false ? unavailable('Atomic replacement requires a writable destination directory.') : available('Temporary files are renamed within the destination directory; write failures are reported.'),
+        externalUrl: desktop && opener ? available('A desktop URL handler is available; execution is checked when used.', opener.command) : unavailable('No usable desktop URL handler/session detected. Open the station homepage manually.'),
+        clipboard: desktop && clipboard ? available('A clipboard command is available; execution is checked when used.', clipboard.command) : unavailable('No usable clipboard command/session detected. RadioCLI can display the text for manual copying.'),
+        terminalReopening: desktop && adapters.terminal ? unverified('A supported installed terminal must be found and its launch verified.', adapters.terminal) : unavailable('No supported graphical terminal session. Use the current TUI or explicitly select headless agent playback.'),
+        backgroundScheduling,
+        catchUp: backgroundScheduling.status === 'available' && evidence.scheduler?.catchUpAfterWake ? available('The native scheduler can deliver a missed occurrence; RadioCLI still enforces the configured grace window.')
+            : backgroundScheduling.status === 'unverified' ? unverified('Catch-up depends on an accessible native user scheduler and its session.') : unavailable('Catch-up delivery is not verified in this session.'),
+        wakeRequests: adapters.scheduler === 'task-scheduler' ? unverified('Task Scheduler can request WakeToRun; hardware, login state, and power policy decide delivery.') : unavailable('No privileged or exact wake request is made on this platform. Catch-up and idle-sleep inhibition are separate capabilities.'),
+        sleepInhibition: sleepTool && has(sleepTool) ? unverified('A sleep-inhibitor tool is installed; its lease must remain alive to provide protection.', sleepTool) : unavailable('No usable per-process sleep inhibitor. Normal playback remains available; sleep may interrupt it.'),
+        systemVolume: volumeTool ? unverified('The system mixer must respond before alarm volume can be raised and restored.', volumeTool) : unavailable('System output volume cannot be adjusted. Set the device volume manually; player volume remains independent.'),
+        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 ? 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(); } };
+}

package/dist/platform/desktop.js

@@ -0,0 +1,36 @@
+import { identifyPlatform } from './runtime.js';
+/** Command plans only. Callers must check the session and observe execution. */
+export function browserCommands(host = identifyPlatform()) {
+    // termux-tools opens one URL through Android's VIEW intent.
+    if (host.id === 'termux')
+        return [{ command: 'termux-open-url', args: [] }];
+    if (host.id === 'darwin')
+        return [{ command: 'open', args: [] }];
+    if (host.id === 'win32')
+        return [{ command: 'explorer', args: [] }];
+    if (['linux', 'freebsd', 'openbsd', 'netbsd'].includes(host.id))
+        return [{ command: 'xdg-open', args: [] }];
+    return [];
+}
+export function clipboardCandidates(host = identifyPlatform()) {
+    // No arguments makes termux-clipboard-set read stdin. Its matching Android
+    // API app and permissions are still required; the caller checks execution.
+    if (host.id === 'termux')
+        return [{ command: 'termux-clipboard-set', args: [] }];
+    if (host.id === 'darwin')
+        return [{ command: 'pbcopy', args: [] }];
+    if (host.id === 'win32')
+        return [{ command: 'clip', args: [] }];
+    if (['linux', 'freebsd', 'openbsd', 'netbsd'].includes(host.id))
+        return [
+            { command: 'wl-copy', args: [] },
+            { command: 'xclip', args: ['-selection', 'clipboard'] },
+            { command: 'xsel', args: ['--clipboard', '--input'] }
+        ];
+    return [];
+}
+export function hasGraphicalSession(host, env = process.env) {
+    if (host.id === 'darwin' || host.id === 'win32' || host.id === 'termux')
+        return !env.SSH_CONNECTION && !env.SSH_TTY;
+    return ['linux', 'freebsd', 'openbsd', 'netbsd'].includes(host.id) && Boolean(env.DISPLAY || env.WAYLAND_DISPLAY);
+}