@ciphore/radiocli 0.2.3 → 0.2.5

package/dist/alarms/terminal-launcher.js

@@ -1,81 +1,32 @@
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
 import { createServer } from 'node:net';
 import { randomBytes } from 'node:crypto';
-import { basename, delimiter, join } from 'node:path';
-const linuxTerminals = new Set(['alacritty', 'foot', 'ghostty', 'gnome-terminal', 'kitty', 'konsole', 'mate-terminal', 'qterminal', 'terminator', 'tilix', 'wezterm', 'xfce4-terminal', 'x-terminal-emulator']);
-export function detectAlarmTerminal(platform = process.platform, env = process.env) {
-    const configured = env.RADIOCLI_ALARM_TERMINAL?.trim();
-    if (configured && validDescriptor(configured, platform))
-        return configured;
-    if (platform === 'darwin') {
-        const program = `${env.TERM_PROGRAM ?? ''} ${env.__CFBundleIdentifier ?? ''}`.toLowerCase();
-        if (program.includes('iterm'))
-            return 'darwin:iterm';
-        if (program.includes('wezterm'))
-            return 'darwin:wezterm';
-        if (program.includes('ghostty'))
-            return 'darwin:ghostty';
-        if (program.includes('kitty'))
-            return 'darwin:kitty';
-        return 'darwin:apple-terminal';
-    }
-    if (platform === 'win32')
-        return env.WT_SESSION ? 'win32:windows-terminal' : 'win32:console';
-    if (platform === 'linux') {
-        const requested = env.TERMINAL?.trim() || env.TERM_PROGRAM?.trim();
-        const resolved = requested ? resolveExecutable(requested, env) : undefined;
-        if (resolved && linuxTerminals.has(basename(resolved)))
-            return `linux:${resolved}`;
-        for (const command of ['ghostty', 'wezterm', 'kitty', 'gnome-terminal', 'konsole', 'xfce4-terminal', 'x-terminal-emulator']) {
-            const path = resolveExecutable(command, env);
-            if (path)
-                return `linux:${path}`;
-        }
-    }
-    return `${platform}:unsupported`;
-}
+import { listenLoopback } from '../platform/loopback.js';
+import { identifyPlatform, nativeAdapters } from '../platform/runtime.js';
+import { detectGraphicalTerminal, launchTerminalCommand } from '../platform/terminals.js';
 export async function openAlarmControls(options) {
     if (options.hasLiveTui?.())
         return { opened: false, terminal: 'existing-tui', message: 'An existing RadioCLI TUI will show the ringing controls.' };
-    const platform = options.platform ?? process.platform;
-    const env = options.env ?? process.env;
-    const terminal = detectAlarmTerminal(platform, env);
-    const command = shellCommand(options.nodePath, options.cliPath, env.RADIOCLI_HOME);
-    const directArgs = environmentCommand(options.nodePath, options.cliPath, env.RADIOCLI_HOME);
-    const launch = options.spawn ?? spawnDetached;
-    if (terminal === 'darwin:apple-terminal')
-        await launched(launch('/usr/bin/osascript', appleTerminalScript(command)));
-    else if (terminal === 'darwin:iterm')
-        await launched(launch('/usr/bin/osascript', iTermScript(command)));
-    else if (terminal === 'darwin:wezterm')
-        await launched(launch('/usr/bin/open', ['-na', 'WezTerm', '--args', 'start', '--always-new-process', '--', ...directArgs]));
-    else if (terminal === 'darwin:ghostty')
-        await launched(launch('/usr/bin/open', ['-na', 'Ghostty', '--args', '-e', ...directArgs]));
-    else if (terminal === 'darwin:kitty')
-        await launched(launch('/usr/bin/open', ['-na', 'kitty', '--args', '--detach', ...directArgs]));
-    else if (terminal === 'win32:windows-terminal')
-        await launched(launch('wt.exe', ['-w', 'new', 'new-tab', '--title', 'RadioCLI Alarm', options.nodePath, options.cliPath]));
-    else if (terminal === 'win32:console')
-        await launched(launch('cmd.exe', ['/d', '/c', 'start', 'RadioCLI Alarm', 'cmd.exe', '/k', windowsCommand(options.nodePath, options.cliPath, env.RADIOCLI_HOME)]));
-    else if (terminal.startsWith('linux:')) {
-        const executable = terminal.slice('linux:'.length);
-        if (!linuxTerminals.has(basename(executable)))
-            throw new Error('Saved Linux terminal is not supported.');
-        const name = basename(executable);
-        const prefix = name === 'gnome-terminal' || name === 'mate-terminal' || name === 'xfce4-terminal' ? ['--'] : name === 'wezterm' ? ['start', '--always-new-process', '--'] : ['-e'];
-        await launched(launch(executable, [...prefix, ...directArgs]));
+    const terminal = await launchTerminalCommand({ ...options, args: [options.cliPath], title: 'RadioCLI Alarm' });
+    if (!options.hasLiveTui)
+        return { opened: false, requested: true, terminal, message: 'Requested RadioCLI alarm controls; TUI startup is unverified.' };
+    const deadline = Date.now() + (options.timeoutMs ?? 8_000);
+    while (true) {
+        if (options.hasLiveTui())
+            return { opened: true, requested: true, terminal, message: 'RadioCLI alarm controls are ready in the saved terminal.' };
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return { opened: false, requested: true, terminal, message: 'Requested RadioCLI alarm controls, but the TUI did not become ready before verification timed out. It may still be starting.' };
+        await new Promise(resolve => setTimeout(resolve, Math.min(50, remaining)));
     }
-    else
-        throw new Error('No supported graphical terminal was found. Open radiocli manually and press ! for alarm controls.');
-    return { opened: true, terminal, message: 'Opened RadioCLI alarm controls in the saved terminal.' };
 }
 /** Ask for macOS Automation access while the user is configuring the alarm. */
 export async function prepareAlarmTerminalAccess(options = {}) {
     const platform = options.platform ?? process.platform;
-    if (platform !== 'darwin')
+    const env = options.env ?? process.env;
+    if (nativeAdapters(identifyPlatform({ platform, env })).terminal !== 'macos')
         return;
-    const terminal = detectAlarmTerminal(platform, options.env ?? process.env);
+    const terminal = detectGraphicalTerminal(platform, env, options.resolve);
     const application = terminal === 'darwin:apple-terminal' ? 'Terminal' : terminal === 'darwin:iterm' ? 'iTerm' : undefined;
     if (!application)
         return;
@@ -94,88 +45,77 @@ export async function verifyAlarmTerminalLaunch(options = {}) {
     const platform = options.platform ?? process.platform;
     const env = options.env ?? process.env;
     await prepareAlarmTerminalAccess(options);
-    const terminal = detectAlarmTerminal(platform, env);
+    const terminal = detectGraphicalTerminal(platform, env, options.resolve);
     if (terminal.endsWith(':unsupported'))
         throw new Error('No supported graphical terminal was found for automatic alarm controls.');
     const token = randomBytes(24).toString('base64url');
     const server = createServer();
-    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', () => resolve()); });
-    const address = server.address();
-    if (!address || typeof address === 'string') {
-        server.close();
-        throw new Error('Unable to create the terminal verification channel.');
-    }
-    const script = "const n=require('node:net');const s=n.connect(Number(process.argv[1]),'127.0.0.1',()=>s.end(process.argv[2]));s.on('error',()=>process.exit(2));";
-    const direct = [options.nodePath ?? process.execPath, '-e', script, String(address.port), token];
-    const command = `${direct.map(shellQuote).join(' ')}; exit`;
-    const launch = options.spawn ?? spawnDetached;
-    const received = new Promise((resolve, reject) => { server.once('connection', socket => { let value = ''; socket.setEncoding('utf8'); socket.on('data', chunk => value += chunk); socket.on('end', () => value === token ? resolve() : reject(new Error('The terminal verification response was not authentic.'))); socket.on('error', reject); }); });
+    const address = await listenLoopback(server);
+    const script = "const n=require('node:net');const s=n.connect(Number(process.argv[1]),process.argv[3],()=>s.end(process.argv[2]));s.on('error',()=>process.exit(2));";
+    const nodePath = options.nodePath ?? process.execPath;
+    const args = ['-e', script, String(address.port), token, address.host];
+    const sockets = new Set();
+    const received = new Promise((resolve, reject) => {
+        server.on('connection', socket => {
+            sockets.add(socket);
+            socket.once('close', () => sockets.delete(socket));
+            let value = '';
+            socket.setEncoding('utf8');
+            socket.on('data', chunk => {
+                value += chunk;
+                if (value.length > token.length) {
+                    socket.destroy();
+                    reject(new Error('The terminal verification response was not authentic.'));
+                }
+            });
+            socket.on('end', () => value === token ? resolve() : reject(new Error('The terminal verification response was not authentic.')));
+            socket.on('error', reject);
+        });
+    });
+    // A callback can fail while the launcher is still reporting its own result.
+    // Keep the rejection observed until it is awaited below.
+    void received.catch(() => undefined);
     try {
-        if (terminal === 'darwin:apple-terminal')
-            await launched(launch('/usr/bin/osascript', appleTerminalScript(command)));
-        else if (terminal === 'darwin:iterm')
-            await launched(launch('/usr/bin/osascript', iTermScript(command)));
-        else if (terminal === 'darwin:wezterm')
-            await launched(launch('/usr/bin/open', ['-na', 'WezTerm', '--args', 'start', '--always-new-process', '--', ...direct]));
-        else if (terminal === 'darwin:ghostty')
-            await launched(launch('/usr/bin/open', ['-na', 'Ghostty', '--args', '-e', ...direct]));
-        else if (terminal === 'darwin:kitty')
-            await launched(launch('/usr/bin/open', ['-na', 'kitty', '--args', '--detach', ...direct]));
-        else if (terminal === 'win32:windows-terminal')
-            await launched(launch('wt.exe', ['-w', 'new', 'new-tab', '--title', 'RadioCLI Alarm Verification', ...direct]));
-        else if (terminal === 'win32:console')
-            await launched(launch('cmd.exe', ['/d', '/c', 'start', 'RadioCLI Alarm Verification', 'cmd.exe', '/c', windowsCommandArgs(direct)]));
-        else if (terminal.startsWith('linux:')) {
-            const executable = terminal.slice(6);
-            const name = basename(executable);
-            const prefix = name === 'gnome-terminal' || name === 'mate-terminal' || name === 'xfce4-terminal' ? ['--'] : name === 'wezterm' ? ['start', '--always-new-process', '--'] : ['-e'];
-            await launched(launch(executable, [...prefix, ...direct]));
-        }
-        else
-            throw new Error('The saved terminal is not supported for alarm controls.');
+        await launchTerminalCommand({ ...options, nodePath, args, title: 'RadioCLI Alarm Verification', closeOnExit: true });
         await withTimeout(received, options.timeoutMs ?? 8_000, 'The terminal opened but did not connect back to RadioCLI.');
         return terminal;
     }
     finally {
+        for (const socket of sockets)
+            socket.destroy();
         await new Promise(resolve => server.close(() => resolve()));
     }
 }
-function validDescriptor(value, platform) {
-    if (platform === 'darwin')
-        return ['darwin:apple-terminal', 'darwin:iterm', 'darwin:wezterm', 'darwin:ghostty', 'darwin:kitty'].includes(value);
-    if (platform === 'win32')
-        return value === 'win32:windows-terminal' || value === 'win32:console';
-    if (platform === 'linux' && value.startsWith('linux:'))
-        return linuxTerminals.has(basename(value.slice(6)));
-    return false;
+function spawnAttached(command, args) {
+    return spawn(command, [...args], { stdio: 'ignore', windowsHide: true });
 }
-function resolveExecutable(input, env) {
-    if (input.includes('/') && existsSync(input))
-        return input;
-    for (const directory of (env.PATH ?? '').split(delimiter)) {
-        const path = join(directory, input);
-        if (existsSync(path))
-            return path;
-    }
-    return undefined;
+function completed(child, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (work) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            work();
+        };
+        const timer = setTimeout(() => {
+            child.kill('SIGTERM');
+            finish(() => reject(new Error('Timed out waiting for the macOS Automation permission response.')));
+        }, timeoutMs);
+        child.once('error', error => finish(() => reject(error)));
+        child.once('close', code => finish(() => resolve(code ?? 1)));
+    });
 }
-function shellQuote(value) { return `'${value.replaceAll("'", `'\\''`)}'`; }
-function shellCommand(nodePath, cliPath, home) { return `${home ? `RADIOCLI_HOME=${shellQuote(home)} ` : ''}${shellQuote(nodePath)} ${shellQuote(cliPath)}`; }
-function environmentCommand(nodePath, cliPath, home) { return home ? ['/usr/bin/env', `RADIOCLI_HOME=${home}`, nodePath, cliPath] : [nodePath, cliPath]; }
-function windowsCommand(nodePath, cliPath, home) { return `${home ? `set "RADIOCLI_HOME=${cmdEscape(home)}" && ` : ''}"${nodePath.replaceAll('"', '""')}" "${cliPath.replaceAll('"', '""')}"`; }
-function windowsCommandArgs(values) { return values.map(value => `"${value.replaceAll('"', '""')}"`).join(' '); }
-function cmdEscape(value) { return value.replaceAll('%', '%%').replaceAll('"', '""').replaceAll('^', '^^').replaceAll('&', '^&').replaceAll('|', '^|').replaceAll('<', '^<').replaceAll('>', '^>'); }
-function appleTerminalScript(command) { return ['-e', 'on run argv', '-e', 'tell application "Terminal"', '-e', 'activate', '-e', 'do script (item 1 of argv)', '-e', 'end tell', '-e', 'end run', command]; }
-function iTermScript(command) { return ['-e', 'on run argv', '-e', 'tell application "iTerm"', '-e', 'activate', '-e', 'set w to (create window with default profile)', '-e', 'tell current session of w to write text (item 1 of argv)', '-e', 'end tell', '-e', 'end run', command]; }
-function spawnDetached(command, args) { return spawn(command, [...args], { detached: true, stdio: 'ignore', windowsHide: false }); }
-function spawnAttached(command, args) { return spawn(command, [...args], { stdio: 'ignore', windowsHide: true }); }
-function launched(child) { return new Promise((resolve, reject) => { child.once('error', reject); child.once('spawn', () => { child.unref(); resolve(); }); }); }
-function completed(child, timeoutMs) { return new Promise((resolve, reject) => { let settled = false; const finish = (work) => { if (settled)
-    return; settled = true; clearTimeout(timer); work(); }; const timer = setTimeout(() => { child.kill('SIGTERM'); finish(() => reject(new Error('Timed out waiting for the macOS Automation permission response.'))); }, timeoutMs); child.once('error', error => finish(() => reject(error))); child.once('close', code => finish(() => resolve(code ?? 1))); }); }
-async function withTimeout(promise, milliseconds, message) { let timer; try {
-    return await Promise.race([promise, new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(message)), milliseconds); })]);
+async function withTimeout(promise, milliseconds, message) {
+    let timer;
+    try {
+        return await Promise.race([promise, new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(message)), milliseconds);
+            })]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
 }
-finally {
-    if (timer)
-        clearTimeout(timer);
-} }

package/dist/alarms/tui-presence.js

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { platformPaths } from '../platform/paths.js';
 import { join } from 'node:path';
 export function registerTuiPresence(root = runtimeDirectory(), pid = process.pid) {
     const directory = join(root, 'tui');
@@ -26,9 +26,7 @@ export function hasLiveTui(root = runtimeDirectory(), alive = processAlive) {
     }
     return false;
 }
-function runtimeDirectory() { if (process.env.RADIOCLI_HOME)
-    return join(process.env.RADIOCLI_HOME, 'runtime'); if (process.platform === 'win32')
-    return join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'RadioCLI', 'runtime'); return join(process.env.XDG_RUNTIME_DIR ?? join(homedir(), '.local', 'state'), 'radiocli'); }
+function runtimeDirectory() { return platformPaths().runtime; }
 function processAlive(pid) { try {
     process.kill(pid, 0);
     return true;

package/dist/cli/arguments.js

@@ -0,0 +1,212 @@
+export const listenerCommands = ['play', 'pause', 'resume', 'stop', 'next', 'previous', 'volume', 'mute', 'unmute', 'now', 'status', 'search', 'countries', 'favorites', 'recent', 'favorite', 'unfavorite', 'preset', 'presets', 'stats', 'completion'];
+const commonFlags = ['--json', '--plain', '--quiet', '-q', '--no-input', '--no-color'];
+const filterFlags = ['--country', '--language', '--codec', '--min-bitrate', '--limit'];
+const commandOptions = {
+    play: ['--favorites', '--recent', '--popular', '--pick', '--source', '--random', '--keep-playing', ...filterFlags],
+    search: ['--pick', ...filterFlags],
+    favorites: ['--pick', '--limit'], recent: ['--pick', '--limit'],
+    countries: ['--limit'], now: ['--watch'], status: ['--watch']
+};
+const booleans = new Set([...commonFlags, '--favorites', '--recent', '--popular', '--pick', '--watch', '--random', '--keep-playing']);
+export function isListenerCommand(value) {
+    return listenerCommands.includes(value);
+}
+export function parseListenerArgs(command, args) {
+    const options = new Map();
+    const words = [];
+    const allowed = new Set([...commonFlags, ...commandOptions[command] ?? []]);
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--') {
+            words.push(...args.slice(index + 1));
+            break;
+        }
+        if (!arg.startsWith('-')) {
+            words.push(arg);
+            continue;
+        }
+        const equal = arg.indexOf('=');
+        const key = equal < 0 ? arg : arg.slice(0, equal);
+        if (!allowed.has(key))
+            throw new Error(`Unknown option: ${key}\nRun radiocli ${command} --help.`);
+        if (options.has(key))
+            throw new Error(`Option ${key} was supplied more than once.`);
+        if (booleans.has(key)) {
+            if (equal >= 0)
+                throw new Error(`${key} does not take a value.`);
+            options.set(key, true);
+        }
+        else {
+            const value = equal >= 0 ? arg.slice(equal + 1) : args[++index];
+            if (!value || value.startsWith('--'))
+                throw new Error(`${key} requires a value. Run radiocli ${command} --help.`);
+            options.set(key, value);
+        }
+    }
+    const flags = { json: options.has('--json'), plain: options.has('--plain'), quiet: options.has('--quiet') || options.has('-q'), noInput: options.has('--no-input'), noColor: options.has('--no-color') };
+    if (flags.json && flags.plain)
+        throw new Error('Choose either --json or --plain.');
+    if ((options.has('--pick') || options.has('--watch')) && (flags.json || flags.plain || flags.quiet || flags.noInput)) {
+        throw new Error('--pick and --watch require interactive output. Omit --json, --plain, --quiet, and --no-input.');
+    }
+    const sources = ['--favorites', '--recent', '--popular', '--source'].filter(option => options.has(option));
+    if (sources.length > 1)
+        throw new Error('Choose one station queue: --favorites, --recent, --popular, or --source.');
+    if (sources[0] && sources[0] !== '--source')
+        options.set('--source', sources[0] === '--favorites' ? 'favorite' : sources[0].slice(2));
+    if (options.get('--source') === 'favorites')
+        options.set('--source', 'favorite');
+    return { command, words, options, flags };
+}
+export function integerOption(value, fallback, label, minimum, maximum) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'string' || !/^\d+$/.test(value) || Number(value) < minimum || Number(value) > maximum)
+        throw new Error(`${label} must be a whole number from ${minimum} through ${maximum}.`);
+    return Number(value);
+}
+const help = {
+    play: `play [station name|provider:id|preset] [options]
+  Start background playback, or control the open TUI. With no station, continue
+  the current station or play your most recent station when nothing is selected.
+  Paused playback resumes; playing audio continues uninterrupted.
+  Exact saved names and presets work offline.
+  Ambiguous names open a numbered chooser only in an interactive terminal.
+
+  --favorites              Play from your favorites
+  --recent                 Play from your recently played stations
+  --popular                Play from the directory's popular stations
+  --random                 Pick randomly from the chosen queue or search
+  --pick                   Choose a station by number
+  --keep-playing           Keep an already playing or paused station
+  --country CODE  --language NAME  --codec NAME  --min-bitrate KBPS
+  --limit 1-100             Search result count (default 20)
+
+  --source recent|favorites|popular|country also works; favorite is accepted
+  for compatibility. Explicit queue or filter options select a station anew.
+
+  Examples:
+    radiocli play jazz
+    radiocli pause
+    radiocli play
+    radiocli play "Groove Salad"
+    radiocli play --favorites --random
+    radiocli play --country JP
+    radiocli play work`,
+    search: `search <query> [options]
+  Find stations. Terminal tables mark favorites with *; piped output is TSV.
+  --pick                 Choose a result and start background playback
+  --country CODE         Filter by two-letter country code
+  --language NAME        Filter by language
+  --codec NAME           Filter by audio codec
+  --min-bitrate KBPS     Minimum bitrate (0-10000)
+  --limit 1-100          Maximum results (default 20)
+
+  Examples:
+    radiocli search jazz --country US --pick
+    radiocli search jazz --json
+    radiocli search jazz --plain`,
+    now: `now [--watch]
+  Show station, track metadata, output, playback state, and volume.
+  --watch updates a single terminal line. Ctrl+C exits the view; audio continues.
+
+  Examples:
+    radiocli now
+    radiocli now --watch
+    radiocli now --json`,
+    status: `status [--watch]
+  Alias for radiocli now. Use --json for the current playback snapshot.`,
+    favorites: `favorites [--limit 1-100] [--pick]
+  List favorite stations, or select one to play with --pick.
+  Save the active station with radiocli favorite.`,
+    recent: `recent [--limit 1-100] [--pick]
+  List recently played stations, newest first. Use --pick to tune one again.`,
+    favorite: `favorite [station name|provider:id|preset]
+  Save a station to favorites. With no argument, save the active station.
+  Example: radiocli favorite "Groove Salad"`,
+    unfavorite: `unfavorite [station name|provider:id|preset]
+  Remove a saved favorite. With no argument, use the active station.`,
+    preset: `preset <save|list|remove> [name] [station name|provider:id|preset]
+  save NAME [STATION] saves a shortcut; omit STATION to save the active station.
+  Saving an existing name replaces its station. Names are case-insensitive,
+  1-40 letters, numbers, hyphens, or underscores, starting with a letter/number.
+  remove NAME removes only the shortcut. Presets are included in library backups.
+
+  Examples:
+    radiocli preset save work
+    radiocli preset save jazz "Example FM"
+    radiocli play work
+    radiocli preset remove work`,
+    presets: `presets
+  List saved station shortcuts. Alias for radiocli preset list.`,
+    countries: `countries [--limit 1-100]
+  Show the most popular countries (default 30).
+  Example: radiocli play --country JP`,
+    volume: `volume <0-100>
+  Set playback volume, or save it for the next session when playback is closed.
+  Example: radiocli volume 40`,
+    pause: `pause
+  Pause the active station. Use radiocli play to continue.`,
+    resume: `resume
+  Resume paused playback. radiocli play also resumes, and can restart after stop.`,
+    stop: `stop
+  Stop ordinary playback and close its background player. Alarms are separate.`,
+    next: `next
+  Play the next station in the current search, favorites, or recent queue.`,
+    previous: `previous
+  Play the previous station in the current queue.`,
+    mute: `mute
+  Mute active playback. Use radiocli unmute to restore sound.`,
+    unmute: `unmute
+  Restore sound without changing the saved volume.`,
+    stats: `stats
+  Show listening time, sessions, streaks, and your most-listened station.
+  Example: radiocli stats --json`,
+    completion: `completion <bash|zsh|fish|powershell>
+  Print a shell completion script. No shell configuration is changed.
+
+  Bash:       source <(radiocli completion bash)
+  Zsh:        source <(radiocli completion zsh)   # after compinit
+  Fish:       radiocli completion fish | source
+  PowerShell: radiocli completion powershell | Out-String | Invoke-Expression
+
+  Add the matching line to your shell profile to enable it in future sessions.`
+};
+export function listenerHelp(command) {
+    return `RadioCLI · ${command}\n\nUsage: radiocli ${help[command]}\n\nOutput options:\n  --json        Structured JSON\n  --plain       Stable tab-separated text without decoration\n  --quiet, -q   Suppress successful output\n  --no-input    Never prompt; use an exact station ID for ambiguous matches\n  --no-color    Disable color\n  --help, -h    Show this help\n`;
+}
+export function completionCandidates(words, presets) {
+    const current = words.at(-1) ?? '';
+    const command = words[0] ?? '';
+    const previous = words.at(-2);
+    let candidates;
+    if (words.length <= 1)
+        candidates = [...listenerCommands, 'help', 'version', 'check', 'doctor', 'setup', 'mcp', 'agent', 'media-controls', 'update', 'import', 'export', 'alarm'];
+    else if (command === 'help')
+        candidates = ['--all', ...listenerCommands, 'check', 'doctor', 'setup', 'mcp', 'agent', 'media-controls', 'update', 'import', 'export', 'alarm', 'version'];
+    else if (command === '--help' || command === '-h')
+        candidates = ['--all'];
+    else if (previous === '--source')
+        candidates = ['recent', 'favorites', 'favorite', 'popular', 'country'];
+    else if (previous === '--country')
+        candidates = ['US', 'GB', 'DE', 'FR', 'JP', 'CA', 'AU', 'BR', 'IN'];
+    else if (previous === '--codec')
+        candidates = ['MP3', 'AAC', 'OGG', 'FLAC'];
+    else if (previous === '--language')
+        candidates = ['english', 'spanish', 'french', 'german', 'japanese'];
+    else if (previous === '--limit')
+        candidates = ['10', '20', '50', '100'];
+    else if (previous === '--min-bitrate')
+        candidates = ['64', '128', '192', '320'];
+    else if (command === 'completion')
+        candidates = ['bash', 'zsh', 'fish', 'powershell'];
+    else if (command === 'preset' && words.length === 2)
+        candidates = ['save', 'list', 'remove'];
+    else if (command === 'volume')
+        candidates = ['0', '20', '40', '60', '80', '100'];
+    else if (isListenerCommand(command))
+        candidates = [...commonFlags, '--help', ...commandOptions[command] ?? [], ...(['play', 'favorite', 'unfavorite', 'preset'].includes(command) ? presets : [])];
+    else
+        candidates = ['--help'];
+    return [...new Set(candidates)].filter(candidate => candidate.startsWith(current));
+}

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.');
+}