@ciphore/radiocli 0.2.1 → 0.2.3

package/dist/alarms/terminal-launcher.js

@@ -0,0 +1,181 @@
+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`;
+}
+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]));
+    }
+    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')
+        return;
+    const terminal = detectAlarmTerminal(platform, options.env ?? process.env);
+    const application = terminal === 'darwin:apple-terminal' ? 'Terminal' : terminal === 'darwin:iterm' ? 'iTerm' : undefined;
+    if (!application)
+        return;
+    const launch = options.spawn ?? spawnAttached;
+    const child = launch('/usr/bin/osascript', ['-e', `tell application "${application}" to count windows`]);
+    const code = await completed(child, options.permissionTimeoutMs ?? 60_000);
+    if (code !== 0)
+        throw new Error(`macOS did not grant RadioCLI permission to control ${application}. Audio can still play, but automatic ringing controls cannot open. Enable Node under System Settings > Privacy & Security > Automation, then press Repair.`);
+}
+/**
+ * Opens the saved terminal with a short-lived authenticated loopback probe. The
+ * terminal exits immediately after proving that a native background job can
+ * expose the ringing TUI on this desktop session.
+ */
+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);
+    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); }); });
+    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 withTimeout(received, options.timeoutMs ?? 8_000, 'The terminal opened but did not connect back to RadioCLI.');
+        return terminal;
+    }
+    finally {
+        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 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 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); })]);
+}
+finally {
+    if (timer)
+        clearTimeout(timer);
+} }

package/dist/alarms/tui-presence.js

@@ -0,0 +1,38 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export function registerTuiPresence(root = runtimeDirectory(), pid = process.pid) {
+    const directory = join(root, 'tui');
+    const path = join(directory, `${pid}.json`);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify({ pid, startedAt: new Date().toISOString() }), { mode: 0o600 });
+    return () => rmSync(path, { force: true });
+}
+export function hasLiveTui(root = runtimeDirectory(), alive = processAlive) {
+    const directory = join(root, 'tui');
+    if (!existsSync(directory))
+        return false;
+    for (const name of readdirSync(directory)) {
+        const path = join(directory, name);
+        try {
+            const value = JSON.parse(readFileSync(path, 'utf8'));
+            if (typeof value.pid === 'number' && Number.isInteger(value.pid) && alive(value.pid))
+                return true;
+            rmSync(path, { force: true });
+        }
+        catch {
+            rmSync(path, { force: true });
+        }
+    }
+    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 processAlive(pid) { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch {
+    return false;
+} }

package/dist/cli.js

@@ -9,12 +9,34 @@ 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, updateCommandForInstall } from './update-check.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';
+const runtime = { nodePath: process.execPath, cliPath: fileURLToPath(import.meta.url) };
 if (isDirectRun(process.argv[1], import.meta.url)) {
     const args = process.argv.slice(2);
-    if (args.length > 0) {
+    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'] }
+        });
+    }
+    else if (args[0] === 'agent-host') {
+        await runHeadlessAgentHost();
+    }
+    else if (args.length > 0) {
         await runCommand(args).catch(error => {
             console.error(error instanceof Error ? error.message : String(error));
             process.exitCode = 1;
@@ -42,20 +64,45 @@ export async function runCommand(args) {
         console.log(appVersion());
         return;
     }
+    if (command === 'alarm') {
+        await runAlarmCommand(rest);
+        return;
+    }
+    if (command === 'mcp') {
+        await runMcpCommand(rest, runtime);
+        return;
+    }
+    if (command === 'agent') {
+        await runAgentCliCommand(rest, runtime);
+        return;
+    }
+    if (command === 'setup') {
+        if (rest.includes('--help') || rest.includes('-h')) {
+            printSetupHelp();
+            return;
+        }
+        await runSetup({ args: rest });
+        return;
+    }
     if (!isKnownCommand(command)) {
         throw new Error(`Unknown command: ${command}\nRun radiocli help.`);
     }
     if (command === 'doctor') {
         const backends = detectPlaybackBackends();
+        const mpvDiagnostic = diagnoseCommand('mpv');
         if (rest.includes('--json')) {
-            console.log(JSON.stringify(doctorReport(backends), null, 2));
+            console.log(JSON.stringify(doctorReport(backends, mpvDiagnostic), null, 2));
             return;
         }
         console.log(`backends=${backends.join(',') || 'none'}`);
+        printMpvDiagnostic(mpvDiagnostic);
         printPlaybackBackendStatus(backends);
         return;
     }
     if (command === 'update') {
+        const unknown = rest.filter(arg => arg !== '--install');
+        if (unknown.length > 0)
+            throw new Error('Usage: radiocli update [--install]');
         const updateCheck = await checkForUpdate();
         const updateCommand = updateCommandForInstall();
         if (updateCheck.error) {
@@ -67,6 +114,26 @@ export async function runCommand(args) {
             console.log(`available=${updateCheck.updateAvailable ? 'yes' : 'no'}`);
         }
         console.log(`command=${updateCommand.command}`);
+        if (rest.includes('--install')) {
+            const result = await installUpdate(updateCommand.command);
+            if (!result.ok)
+                throw new Error(`Update install failed. Run manually: ${result.command}${result.output ? `\n${result.output}` : ''}`);
+            console.log('updated=yes');
+            const agentControl = new JsonLibraryStore().snapshot().settings.agentControl ?? defaultAgentControlSettings;
+            if (agentControl.enabled) {
+                try {
+                    const repaired = await configureMcpIntegrations(true, runtime);
+                    const failed = repaired.filter(item => item.status === 'failed');
+                    console.log(`mcp_repaired=${failed.length ? 'partial' : 'yes'}`);
+                    if (failed.length)
+                        console.log(`mcp_failures=${failed.map(item => `${item.client}: ${item.detail}`).join('; ')}`);
+                }
+                catch (error) {
+                    console.log(`mcp_repaired=failed ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            console.log('restart_required=yes');
+        }
         return;
     }
     if (command === 'check') {
@@ -143,12 +210,17 @@ Usage:
   radiocli version         Print the installed version
   radiocli check           Show provider/backend health
   radiocli doctor [--json] Show local playback setup guidance
+  radiocli setup           Install and verify native playback tools
+  radiocli mcp <command>   Install, inspect, or run the MCP integration
+  radiocli agent <command> Scriptable radio controls for local agents
   radiocli update          Show update availability and install command
+  radiocli update --install Install the latest release and repair enabled MCP entries
   radiocli countries       Print top countries
   radiocli search <query>  Search public stations
   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
 `);
 }
 export function isDirectRun(entryPath, moduleUrl) {
@@ -163,14 +235,31 @@ export function isDirectRun(entryPath, moduleUrl) {
     }
 }
 function isKnownCommand(command) {
-    return ['check', 'doctor', 'update', 'countries', 'search', 'import', 'export', 'add-url'].includes(command);
+    return ['check', 'doctor', 'setup', 'update', 'countries', 'search', 'import', 'export', 'add-url', 'alarm', 'mcp', 'agent'].includes(command);
+}
+function printSetupHelp() {
+    console.log(`RadioCLI Setup
+
+Usage:
+  radiocli setup                         Interactive guided setup
+  radiocli setup --yes                   Install recommended defaults
+  radiocli setup --all --yes             Install mpv, FFmpeg, and VLC
+  radiocli setup --only mpv,ffmpeg       Select specific components
+  radiocli setup --dry-run               Show commands without installing
+  radiocli setup --mcp                   Enable and configure agent MCP clients
+  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
+`);
 }
 function printPlaybackBackendStatus(backends) {
     for (const line of playbackBackendStatusLines(backends)) {
         console.log(line);
     }
 }
-function doctorReport(backends) {
+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 {
@@ -180,6 +269,7 @@ function doctorReport(backends) {
         architecture: process.arch,
         backends,
         commands,
+        mpv: redactDiagnostic(mpvDiagnostic),
         airPlay: {
             available: airPlay.available,
             safe: airPlay.safe,
@@ -191,6 +281,24 @@ function doctorReport(backends) {
         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;

package/dist/player/backend-install.js

@@ -70,12 +70,13 @@ export function playbackBackendLabel(backend) {
     return playbackBackendCapabilities(backend).label;
 }
 export function playbackBackendInstallHint(platform = process.platform, osRelease = readLinuxOsRelease()) {
-    return `Install mpv for playback (${mpvInstallCommand(platform, osRelease)}), then run radiocli doctor.`;
+    return `Run radiocli setup to install mpv for playback (${mpvInstallCommand(platform, osRelease)}), then run radiocli doctor.`;
 }
 export function playbackBackendStatusLines(backends, platform = process.platform, osRelease = readLinuxOsRelease()) {
     const backendSet = new Set(backends);
     const lines = [
         'npm_install=RadioCLI installs the optional AirPlay sender when native dependencies are available; playback tools come from mpv and FFmpeg',
+        'guided_setup=radiocli setup',
         `install_mpv=${mpvInstallCommand(platform, osRelease)}`,
         `optional_ffplay=${ffplayInstallCommand(platform, osRelease)}`
     ];

package/dist/player/command-diagnostics.js

@@ -0,0 +1,27 @@
+import { spawnSync } from 'node:child_process';
+import { resolveCommandDetails } from './command.js';
+export function diagnoseCommand(command, overrides = {}) {
+    const resolution = (overrides.resolve ?? resolveCommandDetails)(command);
+    if (!resolution.path) {
+        return { ...resolution, launchable: false, version: null, error: 'not found' };
+    }
+    const execute = overrides.execute ?? ((path, args, options) => spawnSync(path, args, options));
+    const result = execute(resolution.path, ['--version'], {
+        encoding: 'utf8',
+        timeout: 3000,
+        windowsHide: true
+    });
+    if (result.error) {
+        return { ...resolution, launchable: false, version: null, error: result.error.message };
+    }
+    if (result.status !== 0) {
+        return { ...resolution, launchable: false, version: null, error: `exited with status ${result.status ?? 'unknown'}` };
+    }
+    const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
+    return {
+        ...resolution,
+        launchable: true,
+        version: output.split(/\r?\n/, 1)[0]?.trim() || null,
+        error: null
+    };
+}