@ciphore/radiocli 0.2.4 → 0.2.5

package/dist/alarms/system-volume-linux.js

@@ -0,0 +1,160 @@
+/** Never persist or mutate a default-sink alias: it can change during an alarm. */
+export function linuxVolumeBackend(run, resolve) {
+    const wpctl = resolve('wpctl');
+    if (wpctl) {
+        const identity = async (id) => {
+            const [status, detail] = await Promise.all([
+                checked(run(wpctl, ['status']), 'identify the PipeWire server'),
+                checked(run(wpctl, ['inspect', id]), 'identify the PipeWire output')
+            ]);
+            const server = /^PipeWire .+cookie:\s*(\d{1,20})\]/m.exec(status)?.[1];
+            const node = /^id (\d{1,20}), type PipeWire:Interface:Node\s*$/m.exec(detail)?.[1];
+            const property = (name) => new RegExp(`^\\s*\\*?\\s*${name.replaceAll('.', '\\.')} = "([^"\\r\\n]+)"\\s*$`, 'm').exec(detail)?.[1];
+            const serial = property('object.serial');
+            const name = property('node.name');
+            if (!server || !node || !serial || !/^\d{1,20}$/.test(serial) || !validName(name) || property('media.class') !== 'Audio/Sink')
+                throw new Error('PipeWire returned an unreadable output identity; no default-output mutation is safe.');
+            return { kind: 'pipewire', server, id: node, serial, name };
+        };
+        const verify = async (output) => {
+            if (!output || output.kind === 'pulse')
+                throw changedOutput();
+            const id = output.kind === 'pipewire' ? output.id : output.nodeId;
+            const current = await identity(id);
+            if (current.server !== output.server || current.id !== id || current.serial !== output.serial || current.name !== output.name)
+                throw changedOutput();
+            return id;
+        };
+        return {
+            select: () => identity('@DEFAULT_AUDIO_SINK@'),
+            async read(output) {
+                const id = await verify(output);
+                const text = await checked(run(wpctl, ['get-volume', id]), 'read PipeWire output volume');
+                const match = /Volume:\s*(\d+(?:\.\d+)?)(?:\s|$)/i.exec(text);
+                if (!match)
+                    throw new Error('wpctl returned an unreadable output-volume state.');
+                await verify(output);
+                return { volume: clamp(Number(match[1]) * 100), muted: /\[MUTED\]/i.test(text) };
+            },
+            async write(value, execute = run, output) {
+                const id = await verify(output);
+                await checked(execute(wpctl, ['set-volume', id, `${clamp(value.volume)}%`]), 'set PipeWire output volume');
+                // A hot-unplug between the two commands must not unmute a reused ID.
+                await verify(output);
+                await checked(execute(wpctl, ['set-mute', id, value.muted ? '1' : '0']), 'set PipeWire mute state');
+            }
+        };
+    }
+    const pactl = resolve('pactl');
+    if (pactl) {
+        // The C-locale textual interface also supports PulseAudio versions predating
+        // pactl's JSON output. Its public server cookie changes across restarts.
+        const info = async () => {
+            const text = await checked(run(pactl, ['info']), 'identify the PulseAudio server');
+            const server = /^Cookie:\s*([\da-f]+(?::[\da-f]+)*)\s*$/im.exec(text)?.[1]?.toLowerCase();
+            const name = /^Default Sink:\s*(.+)\s*$/m.exec(text)?.[1]?.trim();
+            if (!validName(server))
+                throw new Error('PulseAudio returned an unreadable server identity; no default-output mutation is safe.');
+            const pipewire = /^Server Name: PulseAudio \(on PipeWire [\w.+-]+\)\s*$/m.test(text);
+            const cookie = /^([\da-f]{1,4}):([\da-f]{1,4})$/.exec(server);
+            if (pipewire && !cookie)
+                throw new Error('PulseAudio returned an unreadable PipeWire server cookie.');
+            // PipeWire's Pulse server exposes the same core cookie as wpctl, rendered
+            // as two hexadecimal words. Classic PulseAudio stays in a separate domain.
+            return { pipewire, server: pipewire ? Number.parseInt(`${cookie[1].padStart(4, '0')}${cookie[2].padStart(4, '0')}`, 16).toString() : server, name: validName(name) ? name : undefined };
+        };
+        const sinks = async (server) => {
+            const text = await checked(run(pactl, server.pipewire ? ['list', 'sinks'] : ['list', 'short', 'sinks']), 'identify PulseAudio outputs');
+            const outputs = server.pipewire ? parsePipeWireSinks(text, server.server) : text.split(/\r?\n/).filter(Boolean).map(line => {
+                const [id, name] = line.split('\t');
+                if (!id || !/^\d{1,20}$/.test(id) || !validName(name))
+                    throw new Error('PulseAudio returned an unreadable output identity.');
+                return { kind: 'pulse', server: server.server, id, name };
+            });
+            if (new Set(outputs.map(item => item.id)).size !== outputs.length || new Set(outputs.map(item => item.name)).size !== outputs.length)
+                throw new Error('PulseAudio returned ambiguous output identities.');
+            return outputs;
+        };
+        const verify = async (output) => {
+            if (!output)
+                throw changedOutput();
+            const server = await info();
+            const outputs = await sinks(server);
+            if (server.server !== output.server)
+                throw changedOutput();
+            const current = outputs.find(item => {
+                if (output.kind === 'pulse')
+                    return item.kind === 'pulse' && item.id === output.id && item.name === output.name;
+                if (item.kind !== 'pulse-pipewire' || item.serial !== output.serial || item.name !== output.name)
+                    return false;
+                return output.kind === 'pipewire' ? item.nodeId === output.id : item.nodeId === output.nodeId && item.id === output.id && item.sinkName === output.sinkName;
+            });
+            if (!current)
+                throw changedOutput();
+            return current.id;
+        };
+        return {
+            async select() {
+                const server = await info();
+                const outputs = await sinks(server);
+                const output = outputs.find(item => (item.kind === 'pulse-pipewire' ? item.sinkName : item.name) === server.name);
+                if (!output)
+                    throw new Error('The default PulseAudio output is unavailable.');
+                return output;
+            },
+            async read(output) {
+                const id = await verify(output);
+                const [volume, mute] = await Promise.all([
+                    checked(run(pactl, ['get-sink-volume', id]), 'read PulseAudio output volume'),
+                    checked(run(pactl, ['get-sink-mute', id]), 'read PulseAudio mute state')
+                ]);
+                const match = /(\d+)%/.exec(volume);
+                const muted = /^Mute:\s*(yes|no)\s*$/im.exec(mute);
+                if (!match || !muted)
+                    throw new Error('pactl returned an unreadable output-volume state.');
+                await verify(output);
+                return { volume: clamp(Number(match[1])), muted: muted[1].toLowerCase() === 'yes' };
+            },
+            async write(value, execute = run, output) {
+                const id = await verify(output);
+                await checked(execute(pactl, ['set-sink-volume', id, `${clamp(value.volume)}%`]), 'set PulseAudio output volume');
+                await verify(output);
+                await checked(execute(pactl, ['set-sink-mute', id, value.muted ? '1' : '0']), 'set PulseAudio mute state');
+            }
+        };
+    }
+    const amixer = resolve('amixer');
+    if (amixer)
+        return {
+            async read() {
+                const text = await checked(run(amixer, ['get', 'Master']), 'read ALSA output volume');
+                const last = [...text.matchAll(/\[(\d+)%\]/g)].at(-1);
+                if (!last)
+                    throw new Error('amixer returned an unreadable output-volume state.');
+                return { volume: clamp(Number(last[1])), muted: /\[off\]/i.test(text) };
+            },
+            async write(value, execute = run) { await checked(execute(amixer, ['set', 'Master', `${clamp(value.volume)}%`, value.muted ? 'mute' : 'unmute']), 'set ALSA output volume'); }
+        };
+    return undefined;
+}
+function parsePipeWireSinks(text, server) {
+    if (!text.trim())
+        return [];
+    return text.split(/(?=^Sink #)/m).filter(block => block.trim()).map(block => {
+        const id = /^Sink #(\d{1,20})\s*$/m.exec(block)?.[1];
+        const sinkName = /^\s+Name:\s*(.+)\s*$/m.exec(block)?.[1]?.trim();
+        const property = (name) => new RegExp(`^\\s+${name.replaceAll('.', '\\.')} = "([^"\\r\\n]+)"\\s*$`, 'm').exec(block)?.[1];
+        const nodeId = property('object.id');
+        const serial = property('object.serial');
+        const name = property('node.name');
+        if (!id || !nodeId || !/^\d{1,20}$/.test(nodeId) || !serial || !/^\d{1,20}$/.test(serial) || !validName(name) || !validName(sinkName))
+            throw new Error('PulseAudio returned an unreadable PipeWire output identity.');
+        return { kind: 'pulse-pipewire', server, id, nodeId, serial, name, sinkName };
+    });
+}
+function changedOutput() { return new Error('The original alarm output disconnected or its audio-server identity changed. Its saved volume was retained; no replacement output was changed.'); }
+function validName(value) { return typeof value === 'string' && value.length > 0 && value.length <= 1024 && !/[\u0000-\u001f\u007f]/.test(value); }
+function clamp(value) { return Math.max(0, Math.min(100, Math.round(Number.isFinite(value) ? value : 0))); }
+async function checked(promise, label) { const result = await promise; if (result.code !== 0)
+    throw new Error(`${label} failed: ${(result.stderr || result.stdout || `exit ${result.code}`).trim()}`); if (Buffer.byteLength(result.stdout) > 64 * 1024)
+    throw new Error(`${label} returned too much data.`); return result.stdout; }

package/dist/alarms/system-volume-ownership.js

@@ -13,9 +13,11 @@ export function defaultSystemVolumeDirectory() {
 export class SystemVolumeOwnership {
     directory;
     timeoutMs;
-    constructor(directory, timeoutMs = 30_000) {
+    output;
+    constructor(directory, timeoutMs = 30_000, output) {
         this.directory = directory;
         this.timeoutMs = timeoutMs;
+        this.output = output;
     }
     async transaction(work) {
         const release = await this.lock();
@@ -27,6 +29,25 @@ export class SystemVolumeOwnership {
         }
     }
     read() {
+        const value = this.readDocument();
+        if (!value)
+            return undefined;
+        if (value.version === 1) {
+            if (!this.output)
+                return value;
+            this.checkLegacy(value);
+            return undefined;
+        }
+        if (!this.output)
+            throw new Error('Saved output-volume ownership belongs to an identified Linux audio device; its recovery state was left intact.');
+        return value.outputs.find(item => sameOutput(item.identity, this.output))?.lease;
+    }
+    /** Enumerate other recovery records while holding the shared root lock. */
+    otherOutputs() {
+        const value = this.readDocument();
+        return this.output && value?.version === 2 ? value.outputs.map(item => item.identity).filter(identity => !sameOutput(identity, this.output)) : [];
+    }
+    readDocument() {
         let text;
         try {
             text = readFileSync(join(this.directory, 'state.json'), 'utf8');
@@ -38,7 +59,11 @@ export class SystemVolumeOwnership {
         }
         try {
             const value = JSON.parse(text);
-            if (value?.version !== 1 || !validId(value.generation) || typeof value.changed !== 'boolean' || !(value.baseline === null ? !value.changed : validSnapshot(value.baseline)) || !Array.isArray(value.participants) || !value.participants.every(item => item && validId(item.id) && validPid(item.pid) && (item.phase === 'pending' || item.phase === 'active')) || new Set(value.participants.map(item => item.id)).size !== value.participants.length)
+            if (value?.version === 2) {
+                if (!Array.isArray(value.outputs) || value.outputs.length > 128 || !value.outputs.every(item => item && validOutput(item.identity) && validLease(item.lease)) || new Set(value.outputs.map(item => outputKey(item.identity))).size !== value.outputs.length)
+                    throw new Error();
+            }
+            else if (!validLease(value))
                 throw new Error();
             return value;
         }
@@ -47,6 +72,19 @@ export class SystemVolumeOwnership {
         }
     }
     save(value) {
+        if (!this.output) {
+            this.writeDocument(value);
+            return;
+        }
+        const existing = this.readDocument();
+        if (existing?.version === 1)
+            this.checkLegacy(existing);
+        const outputs = existing?.version === 2 ? existing.outputs.filter(item => !sameOutput(item.identity, this.output)) : [];
+        if (outputs.length >= 128)
+            throw new Error('Too many unresolved output-volume recovery records; saved output states were retained.');
+        this.writeDocument({ version: 2, outputs: [...outputs, { identity: this.output, lease: value }] });
+    }
+    writeDocument(value) {
         const temporary = join(this.directory, `.state-${process.pid}-${randomUUID()}`);
         try {
             writeFileSync(temporary, JSON.stringify(value), { mode: 0o600, flag: 'wx' });
@@ -60,13 +98,33 @@ export class SystemVolumeOwnership {
             throw error;
         }
     }
-    clear() { try {
-        unlinkSync(join(this.directory, 'state.json'));
+    clear() {
+        if (this.output) {
+            const value = this.readDocument();
+            if (value?.version === 1)
+                this.checkLegacy(value);
+            if (value?.version === 2) {
+                const outputs = value.outputs.filter(item => !sameOutput(item.identity, this.output));
+                if (outputs.length) {
+                    this.writeDocument({ version: 2, outputs });
+                    return;
+                }
+            }
+        }
+        try {
+            unlinkSync(join(this.directory, 'state.json'));
+        }
+        catch (error) {
+            if (codeOf(error) !== 'ENOENT')
+                throw error;
+        }
+    }
+    checkLegacy(value) {
+        // Older Linux jobs recorded only the default sink's volume. That baseline
+        // cannot safely be assigned to whichever device happens to be default now.
+        if (value.changed || value.participants.some(item => item.phase === 'active' && volumeProcessAlive(item.pid)))
+            throw new Error('An earlier alarm saved output-volume ownership without a device identity. Finish its active alarms or repair the saved state.json after checking the original output; the saved state was retained and no output was changed.');
     }
-    catch (error) {
-        if (codeOf(error) !== 'ENOENT')
-            throw error;
-    } }
     /** A null PID is intentional: a crash before PID persistence is ambiguous. */
     beginNativeWrite() { this.saveNativeWrite(null); }
     recordNativeWritePid(pid) { if (!validPid(pid))
@@ -263,5 +321,15 @@ function validPid(value) { return Number.isSafeInteger(value) && Number(value) >
 function validId(value) { return typeof value === 'string' && /^[a-f\d]{8}(?:-[a-f\d]{4}){3}-[a-f\d]{12}$/.test(value); }
 function validSnapshot(value) { if (!value || typeof value !== 'object')
     return false; const state = value; return Number.isInteger(state.volume) && state.volume >= 0 && state.volume <= 100 && typeof state.muted === 'boolean'; }
+function validLease(value) { if (!value || typeof value !== 'object')
+    return false; const state = value; return state.version === 1 && validId(state.generation) && typeof state.changed === 'boolean' && (state.baseline === null ? !state.changed : validSnapshot(state.baseline)) && Array.isArray(state.participants) && state.participants.every(item => item && validId(item.id) && validPid(item.pid) && (item.phase === 'pending' || item.phase === 'active')) && new Set(state.participants.map(item => item.id)).size === state.participants.length; }
+function validOutput(value) { if (!value || typeof value !== 'object')
+    return false; const output = value; return ['pipewire', 'pulse', 'pulse-pipewire'].includes(output.kind) && validLabel(output.server) && validLabel(output.name) && decimalId(output.id) && (output.kind === 'pulse' || decimalId(output.serial)) && (output.kind !== 'pulse-pipewire' || decimalId(output.nodeId) && validLabel(output.sinkName)); }
+function validLabel(value) { return typeof value === 'string' && value.length > 0 && value.length <= 1024 && !/[\u0000-\u001f\u007f]/.test(value); }
+function decimalId(value) { return typeof value === 'string' && /^\d{1,20}$/.test(value); }
+// The PipeWire core, object serial and name identify a sink across both CLIs.
+// Backend-specific IDs remain in the record for independent mutation checks.
+function outputKey(value) { return JSON.stringify(value.kind === 'pulse' ? ['pulse', value.server, value.id, value.name] : ['pipewire', value.server, value.serial, value.name]); }
+function sameOutput(first, second) { return outputKey(first) === outputKey(second); }
 function codeOf(error) { return error?.code; }
 function pause() { return new Promise(resolve => setTimeout(resolve, 20)); }

package/dist/alarms/system-volume.js

@@ -3,17 +3,41 @@ import { randomUUID } from 'node:crypto';
 import { resolveCommand } from '../platform/executables.js';
 import { identifyPlatform, nativeAdapters } from '../platform/runtime.js';
 import { defaultSystemVolumeDirectory, SystemVolumeOwnership, volumeProcessAlive } from './system-volume-ownership.js';
+import { linuxVolumeBackend } from './system-volume-linux.js';
 export function createSystemVolumeController(platform = process.platform, run = runCommand, resolve = resolveCommand, options = {}) {
     const host = identifyPlatform({ platform });
     const adapter = nativeAdapters(host).volume;
-    const backend = adapter === 'macos' ? macBackend(run) : adapter === 'unix-audio' ? linuxBackend(run, resolve) : adapter === 'windows' ? windowsBackend(run, resolve) : undefined;
+    const backend = adapter === 'macos' ? macBackend(run) : adapter === 'unix-audio' ? linuxVolumeBackend(run, resolve) : adapter === 'windows' ? windowsBackend(run, resolve) : undefined;
     return { async acquireMinimum(volume) {
             if (!backend)
                 throw new Error(`System output volume control is unavailable on ${host.id === 'unknown' ? platform : host.id}.`);
-            const ownership = new SystemVolumeOwnership(options.directory ?? defaultSystemVolumeDirectory(), options.lockTimeoutMs);
-            const write = (value) => backend.write(value, run === runCommand ? (command, args) => runCommand(command, args, ownership) : run);
+            const output = await backend.select?.();
+            const directory = options.directory ?? defaultSystemVolumeDirectory();
+            const ownership = new SystemVolumeOwnership(directory, options.lockTimeoutMs, output);
+            const execute = run === runCommand ? (command, args) => runCommand(command, args, ownership) : run;
+            const write = (value) => backend.write(value, execute, output);
             return ownership.transaction(async () => {
                 let state = ownership.read();
+                let pendingRecovery = 0;
+                // Recover dead owners on their still-connected original outputs even if
+                // the default has moved. An unplugged output remains repairable without
+                // preventing a different output from ringing.
+                for (const identity of ownership.otherOutputs()) {
+                    const priorOutput = new SystemVolumeOwnership(directory, options.lockTimeoutMs, identity);
+                    const prior = priorOutput.read();
+                    if (!prior || prior.participants.some(activeParticipant))
+                        continue;
+                    if (prior.changed && prior.baseline) {
+                        try {
+                            await backend.write(prior.baseline, execute, identity);
+                        }
+                        catch {
+                            pendingRecovery += 1;
+                            continue;
+                        }
+                    }
+                    priorOutput.clear();
+                }
                 if (state) {
                     state.participants = state.participants.filter(activeParticipant);
                     if (state.participants.length === 0) {
@@ -26,7 +50,7 @@ export function createSystemVolumeController(platform = process.platform, run =
                     }
                 }
                 const target = clamp(volume);
-                const before = await backend.read();
+                const before = await backend.read(output);
                 const changed = before.muted || before.volume < target;
                 const prior = state;
                 const id = randomUUID();
@@ -66,7 +90,7 @@ export function createSystemVolumeController(platform = process.platform, run =
                 }
                 let released = false;
                 return {
-                    message: changed ? `Local output raised to at least ${target}% and unmuted for the alarm.` : `Local output was already at least ${target}% and unmuted.`,
+                    message: (changed ? `Local output raised to at least ${target}% and unmuted for the alarm.` : `Local output was already at least ${target}% and unmuted.`) + (pendingRecovery ? ` ${pendingRecovery} earlier output recovery record${pendingRecovery === 1 ? ' remains' : 's remain'} unresolved and retained; its original device must be checked.` : ''),
                     async release({ preserve = false } = {}) {
                         if (released)
                             return;
@@ -101,21 +125,6 @@ export function createSystemVolumeController(platform = process.platform, run =
 function activeParticipant(item) { return item.phase === 'active' && volumeProcessAlive(item.pid); }
 function macBackend(run) { return { async read() { const result = await checked(run('/usr/bin/osascript', ['-e', 'set s to get volume settings', '-e', 'return (output volume of s as text) & "," & (output muted of s as text)']), 'read macOS output volume'); const match = /^(\d+)\s*,\s*(true|false)/i.exec(result.stdout.trim()); if (!match)
         throw new Error('macOS returned an unreadable output-volume state.'); return { volume: clamp(Number(match[1])), muted: match[2]?.toLowerCase() === 'true' }; }, async write(value, execute = run) { await checked(execute('/usr/bin/osascript', ['-e', `set volume output volume ${clamp(value.volume)} ${value.muted ? 'with' : 'without'} output muted`]), 'set macOS output volume'); } }; }
-function linuxBackend(run, resolve) {
-    const wpctl = resolve('wpctl');
-    if (wpctl)
-        return { async read() { const result = await checked(run(wpctl, ['get-volume', '@DEFAULT_AUDIO_SINK@']), 'read PipeWire output volume'); const match = /Volume:\s*([\d.]+)/i.exec(result.stdout); if (!match)
-                throw new Error('wpctl returned an unreadable output-volume state.'); return { volume: clamp(Number(match[1]) * 100), muted: /\[MUTED\]/i.test(result.stdout) }; }, async write(value, execute = run) { await checked(execute(wpctl, ['set-volume', '@DEFAULT_AUDIO_SINK@', `${clamp(value.volume)}%`]), 'set PipeWire output volume'); await checked(execute(wpctl, ['set-mute', '@DEFAULT_AUDIO_SINK@', value.muted ? '1' : '0']), 'set PipeWire mute state'); } };
-    const pactl = resolve('pactl');
-    if (pactl)
-        return { async read() { const [volume, mute] = await Promise.all([checked(run(pactl, ['get-sink-volume', '@DEFAULT_SINK@']), 'read PulseAudio output volume'), checked(run(pactl, ['get-sink-mute', '@DEFAULT_SINK@']), 'read PulseAudio mute state')]); const match = /(\d+)%/.exec(volume.stdout); if (!match)
-                throw new Error('pactl returned an unreadable output-volume state.'); return { volume: clamp(Number(match[1])), muted: /yes/i.test(mute.stdout) }; }, async write(value, execute = run) { await checked(execute(pactl, ['set-sink-volume', '@DEFAULT_SINK@', `${clamp(value.volume)}%`]), 'set PulseAudio output volume'); await checked(execute(pactl, ['set-sink-mute', '@DEFAULT_SINK@', value.muted ? '1' : '0']), 'set PulseAudio mute state'); } };
-    const amixer = resolve('amixer');
-    if (amixer)
-        return { async read() { const result = await checked(run(amixer, ['get', 'Master']), 'read ALSA output volume'); const matches = [...result.stdout.matchAll(/\[(\d+)%\]/g)]; const last = matches.at(-1); if (!last)
-                throw new Error('amixer returned an unreadable output-volume state.'); return { volume: clamp(Number(last[1])), muted: /\[off\]/i.test(result.stdout) }; }, async write(value, execute = run) { await checked(execute(amixer, ['set', 'Master', `${clamp(value.volume)}%`, value.muted ? 'mute' : 'unmute']), 'set ALSA output volume'); } };
-    return undefined;
-}
 function windowsBackend(run, resolve) { const powershell = resolve('powershell.exe') ?? resolve('pwsh.exe'); if (!powershell)
     return undefined; return { async read() { const result = await checked(run(powershell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', `${windowsCoreAudio}; [RadioCliVolume]::Get()`]), 'read Windows output volume'); const match = /^(\d+)\s*,\s*(true|false)/im.exec(result.stdout); if (!match)
         throw new Error('Windows returned an unreadable output-volume state.'); return { volume: clamp(Number(match[1])), muted: match[2]?.toLowerCase() === 'true' }; }, async write(value, execute = run) { await checked(execute(powershell, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', `${windowsCoreAudio}; [RadioCliVolume]::Set(${clamp(value.volume)}, $${value.muted ? 'true' : 'false'})`]), 'set Windows output volume'); } }; }
@@ -137,7 +146,7 @@ function runCommand(command, args, ownership) {
         ownership?.beginNativeWrite();
         let child;
         try {
-            child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, timeout: 10_000, killSignal: 'SIGKILL' });
+            child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, timeout: 10_000, killSignal: 'SIGKILL', env: { ...process.env, LC_ALL: 'C' } });
         }
         catch (error) {
             let message = messageOf(error);
@@ -153,8 +162,20 @@ function runCommand(command, args, ownership) {
         let stdout = '';
         let stderr = '';
         let failure;
-        child.stdout.on('data', value => stdout += String(value));
-        child.stderr.on('data', value => stderr += String(value));
+        const append = (value, output) => { const text = String(value); if (output === 'stdout')
+            stdout += text;
+        else
+            stderr += text; if (Buffer.byteLength(stdout) + Buffer.byteLength(stderr) > 64 * 1024) {
+            stdout = stdout.slice(0, 32768);
+            stderr = stderr.slice(0, 32768);
+            failure = 'The output-volume command returned too much data.';
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { }
+        } };
+        child.stdout.on('data', value => append(value, 'stdout'));
+        child.stderr.on('data', value => append(value, 'stderr'));
         // Spawn/kill errors do not prove the helper has closed. Keep ownership until
         // close, including when recording its PID fails after the process starts.
         child.on('error', error => { failure = error.message; });

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