mscfetch 1.0.0 → 1.1.0

package/README.md

@@ -1,37 +1,134 @@
-# mscfetch
+# 🎵 mscfetch
 
-Interactive terminal music search and batch MP3 downloader.
+[![npm version](https://img.shields.io/npm/v/mscfetch.svg?color=cb3837)](https://www.npmjs.com/package/mscfetch)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
 
-## Prerequisites
+An interactive terminal CLI that searches YouTube for audio tracks, accumulates songs into a batch queue across multiple searches, extracts high-quality audio as MP3 (VBR 0, ~320kbps), and embeds ID3 metadata automatically.
 
-- [Node.js](https://nodejs.org/) (v18+)
-- [FFmpeg](https://ffmpeg.org/download.html) in your system PATH (required for audio conversion)
+---
 
-## Usage
+## ⚡ Quick Start
 
-Run directly via `npx` without prior installation:
+Run directly with zero installation via `npx`:
 
 ```bash
 npx mscfetch
 ```
 
-Or install globally:
+Or install globally on your system:
 
 ```bash
 npm install -g mscfetch
 mscfetch
 ```
 
-## Features
+---
 
-- **Interactive Search**: Search YouTube for songs or artists directly from the command line.
-- **Multi-Search Queue**: Accumulate tracks from different searches into a batch queue before downloading.
-- **High Quality Audio**: Extracts highest available audio quality and converts to MP3 (VBR 0, ~320kbps).
-- **Metadata Tags**: Automatically embeds track title, artist, and metadata into MP3 files.
-- **Concurrent Downloads**: Downloads batch items concurrently with a pool of 2 workers.
-- **Sanitized Filenames**: Automatically cleans illegal Windows/Unix filesystem characters.
-- **Cross-Platform**: Saves all downloads directly to `~/Downloads/MusicDownloads`.
+## 📋 Prerequisites
 
-## License
+1. **[Node.js](https://nodejs.org/)** (v18 or higher)
+2. **[FFmpeg](https://ffmpeg.org/download.html)** in your system PATH (required for audio conversion and metadata embedding)
 
-MIT
+### Installing FFmpeg
+
+If FFmpeg is not already installed, `mscfetch` will automatically detect your OS and offer to install it for you (with an explicit option to decline). You can also install it manually:
+
+- **Windows**:
+  ```powershell
+  winget install Gyan.FFmpeg
+  ```
+  *(or via Chocolatey: `choco install ffmpeg`)*
+
+- **macOS**:
+  ```bash
+  brew install ffmpeg
+  ```
+
+- **Linux (Ubuntu/Debian)**:
+  ```bash
+  sudo apt-get update && sudo apt-get install -y ffmpeg
+  ```
+
+---
+
+## 🚀 Features
+
+- **🔍 Metadata-Only Search**: Rapidly searches YouTube using `yt-dlp` without preloading or buffering audio stream data.
+- **📋 Multi-Search Queue**: Search for track 1 (e.g. *When September Ends*), add it to your queue, search for track 2 (e.g. *All I Want*), and download everything together.
+- **🎧 High Quality Audio (VBR 0)**: Converts best audio streams to MP3 using VBR 0 (~320kbps) via FFmpeg.
+- **🏷️ Metadata Tags Embedded**: Embeds artist, track title, and media tags directly into the generated MP3 files.
+- **⚡ 2-Worker Concurrency Pool**: Processes downloads in parallel using an internal concurrency queue limited to 2 workers to prevent throttling.
+- **🛡️ Windows/Unix Filename Sanitizer**: Automatically cleans illegal characters (`<>:"/\|?*`) and protects against path traversal.
+- **📂 Cross-Platform Downloads**: Automatically resolves and saves output directly to `~/Downloads/MusicDownloads`.
+
+---
+
+## 💻 Workflow Example
+
+```
+🎵 Music Fetcher CLI 🎵
+
+? Enter search query (artist or song): Green Day Wake Me Up When September Ends
+✔ Found tracks
+
+? Select tracks to add to queue ('d' to toggle, Enter to confirm, Esc to go back):
+  [ ] Green Day - Wake Me Up When September Ends (Green Day - 4:45)
+  [x] Green Day - Wake Me Up When September Ends [Official Video] (4:45)
+
+✔ Added 1 track(s) to queue. Total in queue: 1
+
+? Queue Menu - choose action:
+❯ ➕ Add more songs to queue (search again)
+  ⬇️ Download queue (1 track)
+  🗑️ Clear queue
+  ❌ Exit
+
+? Enter search query (artist or song): Paramore All I Want
+...
+✔ Added 1 track(s) to queue. Total in queue: 2
+
+? Queue Menu - choose action:
+  ➕ Add more songs to queue (search again)
+❯ ⬇️ Download queue (2 tracks)
+  🗑️ Clear queue
+  ❌ Exit
+
+Starting batch download of 2 track(s)...
+✔ Downloaded: Green Day - Wake Me Up When September Ends [Official Video]
+✔ Downloaded: Paramore - All I Want
+✔ All downloads saved to: C:\Users\...\Downloads\MusicDownloads
+```
+
+---
+
+## 🏗️ Architecture
+
+Built using native ES Modules (`"type": "module"`) following a strict Model-View-Controller (MVC) pattern:
+
+```
+├── bin/
+│   └── index.js              # Executable entrypoint (#!/usr/bin/env node)
+├── src/
+│   ├── config/
+│   │   └── paths.js          # Cross-platform ~/Downloads/MusicDownloads resolution
+│   ├── controllers/
+│   │   └── appController.js  # Main application event & queue loop
+│   ├── models/
+│   │   └── track.js          # Track data structure & duration formatting
+│   ├── services/
+│   │   ├── searchService.js  # yt-dlp metadata query
+│   │   └── downloadService.js# yt-dlp audio extraction & concurrency queue
+│   ├── utils/
+│   │   └── envCheck.js       # FFmpeg presence verification & auto-installer
+│   └── views/
+│       └── terminalView.js   # Terminal prompts, spinners, & menus
+├── package.json
+└── README.md
+```
+
+---
+
+## 📄 License
+
+MIT © [EaRebusa](https://github.com/EaRebusa)

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "mscfetch",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Interactive terminal music search and batch MP3 downloader",
   "main": "./bin/index.js",
   "bin": {
     "mscfetch": "bin/index.js",
     "music-fetch": "bin/index.js"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/EaRebusa/mscfetch.git"
+  },
   "files": [
     "bin",
     "src",
@@ -25,7 +29,7 @@
     "yt-dlp",
     "mscfetch"
   ],
-  "author": "",
+  "author": "EaRebusa",
   "license": "MIT",
   "dependencies": {
     "@inquirer/prompts": "^8.7.4",

package/src/controllers/appController.js

@@ -10,33 +10,54 @@ import {
   displayQueueSummary,
   promptContinue,
   createSpinner,
+  BACK_ACTION,
 } from '../views/terminalView.js';
 import chalk from 'chalk';
 
 export async function runController() {
-  checkFFmpeg();
+  await checkFFmpeg();
   getDownloadDir();
 
   displayBanner();
 
   let queue = [];
   let isRunning = true;
+  let currentScreen = 'search';
+  let canGoBackFromSearch = false;
 
   while (isRunning) {
     try {
-      const query = await promptSearchQuery();
-      const spinner = createSpinner('Searching YouTube...').start();
-      let tracks;
-      try {
-        tracks = await searchTracks(query);
-      } finally {
-        spinner.stop();
-      }
+      if (currentScreen === 'search') {
+        const query = await promptSearchQuery(canGoBackFromSearch);
+        if (query === BACK_ACTION) {
+          if (canGoBackFromSearch) {
+            currentScreen = 'queue_menu';
+            continue;
+          } else {
+            isRunning = false;
+            break;
+          }
+        }
+
+        const spinner = createSpinner('Searching YouTube...').start();
+        let tracks;
+        try {
+          tracks = await searchTracks(query);
+        } finally {
+          spinner.stop();
+        }
+
+        if (!tracks || tracks.length === 0) {
+          console.log(chalk.yellow('No tracks found for your query.'));
+          continue;
+        }
 
-      if (!tracks || tracks.length === 0) {
-        console.log(chalk.yellow('No tracks found for your query.'));
-      } else {
         const selected = await promptTrackSelection(tracks);
+        if (selected === BACK_ACTION) {
+          console.log(chalk.gray('\nTrack selection canceled.'));
+          continue;
+        }
+
         if (selected.length > 0) {
           const newTracks = selected.filter(
             (item) => !queue.some((q) => q.id === item.id || q.url === item.url)
@@ -51,16 +72,20 @@ export async function runController() {
         } else {
           console.log(chalk.yellow('\nNo tracks selected from this search.'));
         }
-      }
 
-      // Queue decision loop: allow searching again, downloading, clearing, or exiting
-      let deciding = true;
-      while (deciding) {
+        currentScreen = 'queue_menu';
+      } else if (currentScreen === 'queue_menu') {
         displayQueueSummary(queue);
         const action = await promptQueueAction(queue);
 
+        if (action === BACK_ACTION || action === 'exit') {
+          isRunning = false;
+          break;
+        }
+
         if (action === 'search') {
-          deciding = false; // loops back to promptSearchQuery
+          currentScreen = 'search';
+          canGoBackFromSearch = true;
         } else if (action === 'download') {
           if (queue.length === 0) {
             console.log(chalk.yellow('Queue is empty. Search and select tracks first.'));
@@ -90,16 +115,18 @@ export async function runController() {
 
           downloadSpinner.stop();
           console.log(chalk.green(`\n✔ All downloads saved to: ${getDownloadDir()}`));
-          queue = []; // Reset queue after download
-          deciding = false;
+          queue = [];
 
-          isRunning = await promptContinue();
+          const continueSession = await promptContinue();
+          if (continueSession) {
+            currentScreen = 'search';
+            canGoBackFromSearch = false;
+          } else {
+            isRunning = false;
+          }
         } else if (action === 'clear') {
           queue = [];
           console.log(chalk.yellow('\nQueue cleared.'));
-        } else if (action === 'exit') {
-          deciding = false;
-          isRunning = false;
         }
       }
     } catch (error) {
@@ -109,7 +136,13 @@ export async function runController() {
       }
       console.error(chalk.red(`Error: ${error.message}`));
       try {
-        isRunning = await promptContinue();
+        const continueSession = await promptContinue();
+        if (continueSession) {
+          currentScreen = 'search';
+          canGoBackFromSearch = queue.length > 0;
+        } else {
+          break;
+        }
       } catch (promptError) {
         if (promptError?.name === 'ExitPromptError') break;
         throw promptError;

package/src/utils/envCheck.js

@@ -1,13 +1,68 @@
 import { execSync } from 'child_process';
+import { confirm } from '@inquirer/prompts';
+import chalk from 'chalk';
+import ora from 'ora';
 
-export function checkFFmpeg() {
+export function isFFmpegInstalled() {
   try {
     execSync('ffmpeg -version', { stdio: 'ignore' });
     return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getInstallCommand() {
+  const platform = process.platform;
+  if (platform === 'win32') {
+    return 'winget install Gyan.FFmpeg --accept-package-agreements --accept-source-agreements';
+  } else if (platform === 'darwin') {
+    return 'brew install ffmpeg';
+  } else {
+    return 'sudo apt-get update && sudo apt-get install -y ffmpeg';
+  }
+}
+
+export async function checkFFmpeg() {
+  if (isFFmpegInstalled()) {
+    return true;
+  }
+
+  console.log(
+    chalk.yellow('\n⚠️  FFmpeg is required for MP3 audio conversion, but was not found in your system PATH.')
+  );
+  const installCmd = getInstallCommand();
+  console.log(chalk.gray(`Detected install command for your system: ${installCmd}\n`));
+
+  let shouldInstall = false;
+  try {
+    shouldInstall = await confirm({
+      message: chalk.cyan('Would you like mscfetch to run this install command for you?'),
+      default: false, // Safe default: user has full choice to decline
+    });
+  } catch (err) {
+    if (err?.name === 'ExitPromptError') {
+      console.log(chalk.gray('\nInstallation aborted.'));
+      process.exit(1);
+    }
+  }
+
+  if (!shouldInstall) {
+    console.log(chalk.gray('\nInstallation declined. You can install FFmpeg manually at any time by running:'));
+    console.log(chalk.bold.white(`  ${installCmd}`));
+    console.log(chalk.gray('Or download directly from https://ffmpeg.org/download.html\n'));
+    process.exit(1);
+  }
+
+  const spinner = ora('Installing FFmpeg...').start();
+  try {
+    execSync(installCmd, { stdio: 'inherit' });
+    spinner.succeed(chalk.green('FFmpeg installation completed!'));
+    return true;
   } catch (error) {
-    console.error('Error: FFmpeg is required but was not found in your system PATH.');
-    console.error('Please install FFmpeg and ensure it is added to your PATH.');
-    console.error('Visit https://ffmpeg.org/download.html for installation instructions.');
+    spinner.fail(chalk.red(`Automatic installation failed: ${error.message}`));
+    console.log(chalk.yellow('\nPlease run the command manually in your terminal/admin prompt:'));
+    console.log(chalk.bold.white(`  ${installCmd}\n`));
     process.exit(1);
   }
 }

package/src/views/customPrompts.js

@@ -0,0 +1,663 @@
+import {
+  createPrompt,
+  useState,
+  useKeypress,
+  usePrefix,
+  usePagination,
+  useMemo,
+  useRef,
+  useEffect,
+  makeTheme,
+  isUpKey,
+  isDownKey,
+  isNumberKey,
+  isEnterKey,
+  isBackspaceKey,
+  isTabKey,
+  ValidationError,
+  Separator,
+} from '@inquirer/core';
+import { cursorHide } from '@inquirer/ansi';
+import { styleText } from 'node:util';
+import figures from '@inquirer/figures';
+
+export const BACK_ACTION = Symbol('BACK');
+
+export function isEscapeKey(key) {
+  return (
+    key.name === 'escape' ||
+    key.name === 'esc' ||
+    (key.sequence === '\x1b' && !key.ctrl && !key.meta && !key.shift)
+  );
+}
+
+export function isToggleKey(key) {
+  return key.name === 'd' || key.name === 'D';
+}
+
+// ---------------------------------------------------------
+// Custom Checkbox Prompt: 'd' toggles, Esc cancels/goes back
+// ---------------------------------------------------------
+const checkboxTheme = {
+  icon: {
+    checked: styleText('green', figures.circleFilled),
+    unchecked: figures.circle,
+    cursor: figures.pointer,
+    disabledChecked: styleText('green', figures.circleDouble),
+    disabledUnchecked: '-',
+  },
+  style: {
+    disabled: (text) => styleText('dim', text),
+    renderSelectedChoices: (selectedChoices) =>
+      selectedChoices.map((choice) => choice.short).join(', '),
+    description: (text) => styleText('cyan', text),
+    keysHelpTip: (keys) =>
+      keys
+        .map(([key, action]) => `${styleText('bold', key)} ${styleText('dim', action)}`)
+        .join(styleText('dim', ' • ')),
+  },
+  i18n: { disabledError: 'This option is disabled and cannot be toggled.' },
+};
+
+function isSelectable(item) {
+  return !Separator.isSeparator(item) && !item.disabled;
+}
+
+function isNavigable(item) {
+  return !Separator.isSeparator(item);
+}
+
+function isChecked(item) {
+  return !Separator.isSeparator(item) && item.checked;
+}
+
+function toggle(item) {
+  return isSelectable(item) ? { ...item, checked: !item.checked } : item;
+}
+
+function check(checked) {
+  return function (item) {
+    return isSelectable(item) ? { ...item, checked } : item;
+  };
+}
+
+function normalizeCheckboxChoices(choices) {
+  return choices.map((choice) => {
+    if (Separator.isSeparator(choice)) return choice;
+    if (typeof choice !== 'object' || choice === null || !('value' in choice)) {
+      const name = String(choice);
+      return {
+        value: choice,
+        name,
+        short: name,
+        checkedName: name,
+        disabled: false,
+        checked: false,
+      };
+    }
+    const name = choice.name ?? String(choice.value);
+    const normalizedChoice = {
+      value: choice.value,
+      name,
+      short: choice.short ?? name,
+      checkedName: choice.checkedName ?? name,
+      disabled: choice.disabled ?? false,
+      checked: choice.checked ?? false,
+    };
+    if (choice.description) {
+      normalizedChoice.description = choice.description;
+    }
+    return normalizedChoice;
+  });
+}
+
+export const customCheckbox = createPrompt((config, done) => {
+  const { pageSize = 7, loop = true, required, validate = () => true } = config;
+  const shortcuts = { all: 'a', invert: 'i', ...config.shortcuts };
+  const theme = makeTheme(checkboxTheme, config.theme);
+  const { keybindings } = theme;
+  const [status, setStatus] = useState('idle');
+  const prefix = usePrefix({ status, theme });
+  const [items, setItems] = useState(normalizeCheckboxChoices(config.choices));
+  const isCancelledRef = useRef(false);
+
+  const bounds = useMemo(() => {
+    const first = items.findIndex(isNavigable);
+    const last = items.findLastIndex(isNavigable);
+    if (first === -1) {
+      throw new ValidationError('[checkbox prompt] No selectable choices. All choices are disabled.');
+    }
+    return { first, last };
+  }, [items]);
+
+  const [active, setActive] = useState(bounds.first);
+  const [errorMsg, setError] = useState();
+
+  useKeypress(async (key) => {
+    if (status !== 'idle') return;
+
+    if (isEscapeKey(key)) {
+      isCancelledRef.current = true;
+      setStatus('done');
+      done(BACK_ACTION);
+      return;
+    }
+
+    if (isEnterKey(key)) {
+      setStatus('loading');
+      const selection = items.filter(isChecked);
+      const isValid = await validate([...selection]);
+      setStatus('idle');
+      if (required && !selection.length) {
+        setError('At least one choice must be selected');
+      } else if (isValid === true) {
+        setStatus('done');
+        done(selection.map((choice) => choice.value));
+      } else {
+        setError(isValid || 'You must select a valid value');
+      }
+    } else if (isUpKey(key, keybindings) || isDownKey(key, keybindings)) {
+      if (errorMsg) setError(undefined);
+      if (
+        loop ||
+        (isUpKey(key, keybindings) && active !== bounds.first) ||
+        (isDownKey(key, keybindings) && active !== bounds.last)
+      ) {
+        const offset = isUpKey(key, keybindings) ? -1 : 1;
+        let next = active;
+        do {
+          next = (next + offset + items.length) % items.length;
+        } while (!isNavigable(items[next]));
+        setActive(next);
+      }
+    } else if (isToggleKey(key)) {
+      const activeItem = items[active];
+      if (activeItem && !Separator.isSeparator(activeItem)) {
+        if (activeItem.disabled) {
+          setError(theme.i18n.disabledError);
+        } else {
+          setError(undefined);
+          setItems(items.map((choice, i) => (i === active ? toggle(choice) : choice)));
+        }
+      }
+    } else if (key.name === shortcuts.all) {
+      const selectAll = items.some((choice) => isSelectable(choice) && !choice.checked);
+      setItems(items.map(check(selectAll)));
+    } else if (key.name === shortcuts.invert) {
+      setItems(items.map(toggle));
+    } else if (isNumberKey(key)) {
+      const selectedIndex = Number(key.name) - 1;
+      let selectableIndex = -1;
+      const position = items.findIndex((item) => {
+        if (Separator.isSeparator(item)) return false;
+        selectableIndex++;
+        return selectableIndex === selectedIndex;
+      });
+      const selectedItem = items[position];
+      if (selectedItem && isSelectable(selectedItem)) {
+        setActive(position);
+        setItems(items.map((choice, i) => (i === position ? toggle(choice) : choice)));
+      }
+    }
+  });
+
+  const message = theme.style.message(config.message, status);
+  let description;
+  const page = usePagination({
+    items,
+    active,
+    renderItem({ item, isActive }) {
+      if (Separator.isSeparator(item)) {
+        return ` ${item.separator}`;
+      }
+      const cursor = isActive ? theme.icon.cursor : ' ';
+      if (item.disabled) {
+        const disabledLabel = typeof item.disabled === 'string' ? item.disabled : '(disabled)';
+        const checkbox = item.checked
+          ? theme.icon.disabledChecked
+          : theme.icon.disabledUnchecked;
+        return theme.style.disabled(`${cursor}${checkbox} ${item.name} ${disabledLabel}`);
+      }
+      if (isActive) {
+        description = item.description;
+      }
+      const checkbox = item.checked ? theme.icon.checked : theme.icon.unchecked;
+      const name = item.checked ? item.checkedName : item.name;
+      const color = isActive ? theme.style.highlight : (x) => x;
+      return color(`${cursor}${checkbox} ${name}`);
+    },
+    pageSize,
+    loop,
+  });
+
+  if (status === 'done') {
+    if (isCancelledRef.current) {
+      return [prefix, message, theme.style.disabled('(back)')].filter(Boolean).join(' ');
+    }
+    const selection = items.filter(isChecked);
+    const answer = theme.style.answer(theme.style.renderSelectedChoices(selection, items));
+    return [prefix, message, answer].filter(Boolean).join(' ');
+  }
+
+  const keys = [
+    ['↑↓', 'navigate'],
+    ['d', 'toggle'],
+  ];
+  if (shortcuts.all) keys.push([shortcuts.all, 'all']);
+  if (shortcuts.invert) keys.push([shortcuts.invert, 'invert']);
+  keys.push(['esc', 'back']);
+  keys.push(['⏎', 'submit']);
+  const helpLine = theme.style.keysHelpTip(keys);
+
+  const lines = [
+    [prefix, message].filter(Boolean).join(' '),
+    page,
+    ' ',
+    description ? theme.style.description(description) : '',
+    errorMsg ? theme.style.error(errorMsg) : '',
+    helpLine,
+  ]
+    .filter(Boolean)
+    .join('\n')
+    .trimEnd();
+
+  return `${lines}${cursorHide}`;
+});
+
+// ---------------------------------------------------------
+// Custom Input Prompt: Esc cancels / goes back
+// ---------------------------------------------------------
+const inputTheme = {
+  validationFailureMode: 'keep',
+};
+
+export const customInput = createPrompt((config, done) => {
+  const { prefill = 'tab' } = config;
+  const theme = makeTheme(inputTheme, config.theme);
+  const [status, setStatus] = useState('idle');
+  const [defaultValue, setDefaultValue] = useState(String(config.default ?? ''));
+  const [errorMsg, setError] = useState();
+  const [value, setValue] = useState('');
+  const isCancelledRef = useRef(false);
+  const prefix = usePrefix({ status, theme });
+
+  async function validate(val) {
+    const { required, pattern, patternError = 'Invalid input' } = config;
+    if (required && !val) return 'You must provide a value';
+    if (pattern && !pattern.test(val)) return patternError;
+    if (typeof config.validate === 'function') {
+      return (await config.validate(val)) || 'You must provide a valid value';
+    }
+    return true;
+  }
+
+  useKeypress(async (key, rl) => {
+    if (status !== 'idle') return;
+
+    if (isEscapeKey(key)) {
+      rl.clearLine(0);
+      isCancelledRef.current = true;
+      setStatus('done');
+      done(BACK_ACTION);
+      return;
+    }
+
+    if (isEnterKey(key)) {
+      const answer = value || defaultValue;
+      setStatus('loading');
+      const isValid = await validate(answer);
+      if (isValid === true) {
+        setValue(answer);
+        setStatus('done');
+        done(answer);
+      } else {
+        if (theme.validationFailureMode === 'clear') {
+          setValue('');
+        } else {
+          rl.write(value);
+        }
+        setError(isValid);
+        setStatus('idle');
+      }
+    } else if (isBackspaceKey(key) && !value) {
+      setDefaultValue('');
+    } else if (isTabKey(key) && !value) {
+      setDefaultValue('');
+      rl.clearLine(0);
+      rl.write(defaultValue);
+      setValue(defaultValue);
+    } else {
+      setDefaultValue('');
+      setValue(rl.line);
+      setError(undefined);
+    }
+  });
+
+  useEffect((rl) => {
+    if (prefill === 'editable' && defaultValue) {
+      rl.write(defaultValue);
+      setValue(defaultValue);
+    }
+  }, []);
+
+  const message = theme.style.message(config.message, status);
+  let formattedValue = value;
+  if (status === 'done' && isCancelledRef.current) {
+    formattedValue = theme.style.disabled ? theme.style.disabled('(back)') : '(back)';
+  } else if (typeof config.transformer === 'function') {
+    formattedValue = config.transformer(value, { isFinal: status === 'done' });
+  } else if (status === 'done') {
+    formattedValue = theme.style.answer(value);
+  }
+
+  let defaultStr;
+  if (defaultValue && status !== 'done' && !value) {
+    defaultStr = theme.style.defaultAnswer(defaultValue);
+  }
+
+  let error = '';
+  if (errorMsg) {
+    error = theme.style.error(errorMsg);
+  }
+
+  return [
+    [prefix, message, defaultStr, formattedValue]
+      .filter((v) => v !== undefined)
+      .join(' '),
+    error,
+  ];
+});
+
+// ---------------------------------------------------------
+// Custom Select Prompt: Esc cancels / goes back
+// ---------------------------------------------------------
+const selectTheme = {
+  icon: { cursor: figures.pointer },
+  style: {
+    disabled: (text) => styleText('dim', text),
+    description: (text) => styleText('cyan', text),
+    keysHelpTip: (keys) =>
+      keys
+        .map(([key, action]) => `${styleText('bold', key)} ${styleText('dim', action)}`)
+        .join(styleText('dim', ' • ')),
+  },
+  i18n: { disabledError: 'This option is disabled and cannot be selected.' },
+  indexMode: 'hidden',
+};
+
+function normalizeSelectChoices(choices) {
+  return choices.map((choice) => {
+    if (Separator.isSeparator(choice)) return choice;
+    if (typeof choice !== 'object' || choice === null || !('value' in choice)) {
+      const name = String(choice);
+      return {
+        value: choice,
+        name,
+        short: name,
+        disabled: false,
+      };
+    }
+    const name = choice.name ?? String(choice.value);
+    const normalizedChoice = {
+      value: choice.value,
+      name,
+      short: choice.short ?? name,
+      disabled: choice.disabled ?? false,
+    };
+    if (choice.description) {
+      normalizedChoice.description = choice.description;
+    }
+    return normalizedChoice;
+  });
+}
+
+export const customSelect = createPrompt((config, done) => {
+  const { loop = true, pageSize = 7 } = config;
+  const theme = makeTheme(selectTheme, config.theme);
+  const { keybindings } = theme;
+  const [status, setStatus] = useState('idle');
+  const prefix = usePrefix({ status, theme });
+  const searchTimeoutRef = useRef();
+  const isCancelledRef = useRef(false);
+  const searchEnabled = !keybindings.includes('vim');
+  const items = useMemo(() => normalizeSelectChoices(config.choices), [config.choices]);
+  const bounds = useMemo(() => {
+    const first = items.findIndex(isNavigable);
+    const last = items.findLastIndex(isNavigable);
+    if (first === -1) {
+      throw new ValidationError('[select prompt] No selectable choices. All choices are disabled.');
+    }
+    return { first, last };
+  }, [items]);
+
+  const [active, setActive] = useState(bounds.first);
+  const [errorMsg, setError] = useState();
+  const selectedChoice = items[active];
+
+  useKeypress((key, rl) => {
+    clearTimeout(searchTimeoutRef.current);
+    if (errorMsg) setError(undefined);
+
+    if (isEscapeKey(key)) {
+      isCancelledRef.current = true;
+      setStatus('done');
+      done(BACK_ACTION);
+      return;
+    }
+
+    if (isEnterKey(key)) {
+      if (selectedChoice.disabled) {
+        setError(theme.i18n.disabledError);
+      } else {
+        setStatus('done');
+        done(selectedChoice.value);
+      }
+    } else if (isUpKey(key, keybindings) || isDownKey(key, keybindings)) {
+      rl.clearLine(0);
+      if (
+        loop ||
+        (isUpKey(key, keybindings) && active !== bounds.first) ||
+        (isDownKey(key, keybindings) && active !== bounds.last)
+      ) {
+        const offset = isUpKey(key, keybindings) ? -1 : 1;
+        let next = active;
+        do {
+          next = (next + offset + items.length) % items.length;
+        } while (!isNavigable(items[next]));
+        setActive(next);
+      }
+    } else if (isNumberKey(key) && !Number.isNaN(Number(rl.line))) {
+      const selectedIndex = Number(rl.line) - 1;
+      let selectableIndex = -1;
+      const position = items.findIndex((item) => {
+        if (Separator.isSeparator(item)) return false;
+        selectableIndex++;
+        return selectableIndex === selectedIndex;
+      });
+      const item = items[position];
+      if (item != null && isSelectable(item)) {
+        setActive(position);
+      }
+      searchTimeoutRef.current = setTimeout(() => {
+        rl.clearLine(0);
+      }, 700);
+    } else if (isBackspaceKey(key)) {
+      rl.clearLine(0);
+    } else if (searchEnabled) {
+      const searchTerm = rl.line.toLowerCase();
+      const matchIndex = items.findIndex((item) => {
+        if (Separator.isSeparator(item) || !isSelectable(item)) return false;
+        return item.name.toLowerCase().startsWith(searchTerm);
+      });
+      if (matchIndex !== -1) {
+        setActive(matchIndex);
+      }
+      searchTimeoutRef.current = setTimeout(() => {
+        rl.clearLine(0);
+      }, 700);
+    }
+  });
+
+  useEffect(() => () => {
+    clearTimeout(searchTimeoutRef.current);
+  }, []);
+
+  const message = theme.style.message(config.message, status);
+  const helpLine = theme.style.keysHelpTip([
+    ['↑↓', 'navigate'],
+    ['esc', 'back'],
+    ['⏎', 'select'],
+  ]);
+
+  let separatorCount = 0;
+  const page = usePagination({
+    items,
+    active,
+    renderItem({ item, isActive, index }) {
+      if (Separator.isSeparator(item)) {
+        separatorCount++;
+        return ` ${item.separator}`;
+      }
+      const cursor = isActive ? theme.icon.cursor : ' ';
+      const indexLabel = theme.indexMode === 'number' ? `${index + 1 - separatorCount}. ` : '';
+      if (item.disabled) {
+        const disabledLabel = typeof item.disabled === 'string' ? item.disabled : '(disabled)';
+        const disabledCursor = isActive ? theme.icon.cursor : '-';
+        return theme.style.disabled(`${disabledCursor} ${indexLabel}${item.name} ${disabledLabel}`);
+      }
+      const color = isActive ? theme.style.highlight : (x) => x;
+      return color(`${cursor} ${indexLabel}${item.name}`);
+    },
+    pageSize,
+    loop,
+  });
+
+  if (status === 'done') {
+    if (isCancelledRef.current) {
+      return [prefix, message, theme.style.disabled ? theme.style.disabled('(back)') : '(back)']
+        .filter(Boolean)
+        .join(' ');
+    }
+    return [prefix, message, theme.style.answer(selectedChoice.short)]
+      .filter(Boolean)
+      .join(' ');
+  }
+
+  const { description } = selectedChoice;
+  const lines = [
+    [prefix, message].filter(Boolean).join(' '),
+    page,
+    ' ',
+    description ? theme.style.description(description) : '',
+    errorMsg ? theme.style.error(errorMsg) : '',
+    helpLine,
+  ]
+    .filter(Boolean)
+    .join('\n')
+    .trimEnd();
+
+  return `${lines}${cursorHide}`;
+});
+
+// ---------------------------------------------------------
+// Custom Confirm Prompt: Esc acts as 'no'
+// ---------------------------------------------------------
+const confirmTheme = {
+  keywords: {
+    yes: 'Yes',
+    no: 'No',
+    error: ({ yes, no }) => `You must answer with "${yes}" or "${no}"`,
+  },
+  style: {
+    confirmDefault: (text) => {
+      const first = text[0] ?? '';
+      if (first.toLowerCase() === first.toUpperCase()) {
+        return styleText('cyan', text);
+      }
+      return first.toUpperCase() + text.slice(1);
+    },
+  },
+};
+
+export const customConfirm = createPrompt((config, done) => {
+  const [status, setStatus] = useState('idle');
+  const [value, setValue] = useState('');
+  const [errorMsg, setError] = useState();
+  const theme = makeTheme(confirmTheme, config.theme);
+  const prefix = usePrefix({ status, theme });
+  const { yes, no } = theme.keywords;
+  const isCancelledRef = useRef(false);
+
+  const yesHint = (yes[0] ?? '').toLowerCase();
+  const noHint = (no[0] ?? '').toLowerCase();
+  const hint =
+    config.default === false
+      ? `${yesHint}/${theme.style.confirmDefault(noHint)}`
+      : `${theme.style.confirmDefault(yesHint)}/${noHint}`;
+
+  function boolToString(val) {
+    return val ? yes : no;
+  }
+  const { transformer = boolToString } = config;
+
+  function getBooleanValue(val) {
+    const v = val.trim().toLowerCase();
+    if (v === '') return config.default !== false;
+    if (yes.toLowerCase().startsWith(v)) return true;
+    if (no.toLowerCase().startsWith(v)) return false;
+    if ('yes'.startsWith(v)) return true;
+    if ('no'.startsWith(v)) return false;
+    return undefined;
+  }
+
+  useKeypress((key, rl) => {
+    if (status !== 'idle') return;
+
+    if (isEscapeKey(key)) {
+      isCancelledRef.current = true;
+      setStatus('done');
+      done(false);
+      return;
+    }
+
+    if (isEnterKey(key)) {
+      const answer = getBooleanValue(value);
+      if (typeof answer === 'boolean') {
+        setStatus('done');
+        done(answer);
+      } else {
+        setError(theme.keywords.error({ yes, no }));
+      }
+    } else if (isBackspaceKey(key)) {
+      rl.clearLine(0);
+      setValue('');
+      setError(undefined);
+    } else {
+      setValue(rl.line);
+      setError(undefined);
+    }
+  });
+
+  const message = theme.style.message(config.message, status);
+  let formattedValue = value;
+  let defaultValue = '';
+  if (status === 'done') {
+    if (isCancelledRef.current) {
+      formattedValue = theme.style.answer(no);
+    } else {
+      formattedValue = theme.style.answer(value || transformer(config.default !== false));
+    }
+  } else {
+    defaultValue = ` ${theme.style.defaultAnswer(hint)}`;
+  }
+
+  let error = '';
+  if (errorMsg) {
+    error = theme.style.error(errorMsg);
+  }
+
+  return [
+    `${prefix} ${message}${defaultValue} ${formattedValue}`,
+    error,
+  ];
+});

package/src/views/terminalView.js

@@ -1,10 +1,19 @@
-import { input, checkbox, confirm, select } from '@inquirer/prompts';
 import chalk from 'chalk';
 import ora from 'ora';
+import {
+  customCheckbox,
+  customInput,
+  customSelect,
+  customConfirm,
+  BACK_ACTION,
+} from './customPrompts.js';
 
-export async function promptSearchQuery() {
-  return await input({
-    message: chalk.cyan('Enter search query (artist or song):'),
+export { BACK_ACTION };
+
+export async function promptSearchQuery(canGoBack = false) {
+  const escHint = canGoBack ? 'Esc to go back' : 'Esc to exit';
+  return await customInput({
+    message: chalk.cyan(`Enter search query (artist or song) [${escHint}]:`),
     validate: (value) => value.trim().length > 0 || 'Query cannot be empty',
   });
 }
@@ -16,8 +25,8 @@ export async function promptTrackSelection(tracks) {
     checked: false, // Default to unchecked per user preference
   }));
 
-  return await checkbox({
-    message: chalk.cyan('Select tracks to add to queue (Space to toggle, Enter to confirm):'),
+  return await customCheckbox({
+    message: chalk.cyan("Select tracks to add to queue ('d' to toggle, Enter to confirm, Esc to go back):"),
     choices,
   });
 }
@@ -47,8 +56,8 @@ export async function promptQueueAction(queue) {
     value: 'exit',
   });
 
-  return await select({
-    message: chalk.cyan('Queue Menu - choose action:'),
+  return await customSelect({
+    message: chalk.cyan('Queue Menu - choose action (Esc to exit):'),
     choices,
   });
 }
@@ -67,7 +76,7 @@ export function displayQueueSummary(queue) {
 }
 
 export async function promptContinue() {
-  return await confirm({
+  return await customConfirm({
     message: chalk.cyan('Would you like to start another search session?'),
     default: true,
   });