ssdl 1.0.0

package/src/screens/Search.js

@@ -0,0 +1,100 @@
+import { render, c } from '../tui/renderer.js';
+import { textInput, menuSelect } from '../tui/input.js';
+import { searchTracks } from '../services/spotify.js';
+import { formatDuration, truncate } from '../utils/format.js';
+
+/**
+ * Show the search screen — search Spotify for tracks
+ * @returns {Promise<object|null>} Selected track object, or null if cancelled
+ */
+export async function showSearch(input) {
+    // Step 1: Get search query
+    const query = await textInput(input, (text) => {
+        let content = '\n';
+        content += c.brightCyan('  Search Spotify\n\n');
+        content += `  > ${text}${c.dim('|')}\n\n`;
+
+        if (!text.trim()) {
+            content += c.dim('  Type a song name, artist, or both\n');
+        } else {
+            content += c.dim(`  Press Enter to search for "${text}"\n`);
+        }
+
+        content += '\n' + c.dim('  Enter search | Esc back');
+        render(content);
+    });
+
+    if (!query) return null;
+
+    // Step 2: Show loading with dots animation
+    render('\n' + c.cyan('  Searching Spotify...'));
+
+    // Step 3: Search Spotify
+    let results;
+    try {
+        results = await searchTracks(query, 10);
+    } catch (err) {
+        render(
+            '\n' +
+            c.red(`  Search failed: ${err.message}\n\n`) +
+            c.dim('  Press Enter to go back')
+        );
+        return new Promise((resolve) => {
+            input.clearHandlers();
+            input.on('return', () => { input.clearHandlers(); resolve(null); });
+            input.on('escape', () => { input.clearHandlers(); resolve(null); });
+        });
+    }
+
+    if (!results || results.length === 0) {
+        render(
+            '\n' +
+            c.yellow(`  No results for "${query}"\n\n`) +
+            c.dim('  Try a different search term\n\n') +
+            c.dim('  Press Enter to go back')
+        );
+        return new Promise((resolve) => {
+            input.clearHandlers();
+            input.on('return', () => { input.clearHandlers(); resolve(null); });
+            input.on('escape', () => { input.clearHandlers(); resolve(null); });
+        });
+    }
+
+    // Step 4: Show results with aligned columns
+    const selectedIdx = await menuSelect(results, input, (items, selected) => {
+        let content = '\n';
+        content += c.brightCyan(`  Results for "${query}"`) + c.dim(`  (${items.length} found)\n\n`);
+
+        // Calculate column widths for alignment
+        const maxTitle = 30;
+        const maxArtist = 20;
+
+        items.forEach((track, i) => {
+            const isActive = i === selected;
+            const prefix = isActive ? c.brightCyan('  > ') : '    ';
+            const num = c.dim(`${String(i + 1).padStart(2)}.`);
+            const title = truncate(track.title, maxTitle);
+            const artist = truncate(track.artist, maxArtist);
+            const dur = formatDuration(track.duration);
+
+            if (isActive) {
+                content += `${prefix}${num} ${c.brightWhite(title.padEnd(maxTitle))}  ${c.cyan(artist.padEnd(maxArtist))}  ${c.dim(dur)}\n`;
+            } else {
+                content += `${prefix}${num} ${title.padEnd(maxTitle)}  ${c.dim(artist.padEnd(maxArtist))}  ${c.dim(dur)}\n`;
+            }
+        });
+
+        // Show details of selected track
+        const sel = items[selected];
+        content += '\n';
+        content += c.dim('  ─────────────────────────────────────────────────────\n');
+        content += `  ${c.brightWhite(sel.title)}\n`;
+        content += `  ${c.cyan(sel.artist)}  ${c.dim('on')}  ${c.dim(sel.album)}\n`;
+        content += `  ${c.dim(formatDuration(sel.duration))}\n`;
+        content += '\n' + c.dim('  up/down navigate | Enter download | Esc back');
+        render(content);
+    });
+
+    if (selectedIdx === -1) return null;
+    return results[selectedIdx];
+}

package/src/screens/TrackList.js

@@ -0,0 +1,85 @@
+import { render, drawTable, c } from '../tui/renderer.js';
+import { checkboxSelect } from '../tui/input.js';
+import { formatDuration, truncate } from '../utils/format.js';
+
+/**
+ * Show the track list / playlist preview with checkbox selection
+ * @param {object} data - Playlist/album data with tracks array
+ * @param {string} type - 'track' | 'playlist' | 'album'
+ * @returns {Promise<object[]|null>} Selected tracks, or null if cancelled
+ */
+export async function showTrackList(data, type, input) {
+    // Single track — data is already an array like [trackObj], return as-is
+    if (type === 'track') {
+        return data;
+    }
+
+    const tracks = data.tracks;
+
+    const selectedSet = await checkboxSelect(tracks, input, (items, selectedIdx, checked) => {
+        let content = '\n';
+
+        // Header with metadata
+        if (type === 'playlist') {
+            content += c.brightCyan(`  Playlist: ${data.name}\n`);
+            content += c.dim(`  by ${data.owner}  |  ${tracks.length} tracks`);
+            const totalMs = tracks.reduce((s, t) => s + (t.duration || 0), 0);
+            content += c.dim(`  |  ${formatDuration(totalMs)} total\n`);
+        } else if (type === 'album') {
+            content += c.brightCyan(`  Album: ${data.name}\n`);
+            content += c.dim(`  by ${data.artist}  |  ${tracks.length} tracks`);
+            if (data.releaseDate) content += c.dim(`  |  ${data.releaseDate.slice(0, 4)}`);
+            content += '\n';
+        }
+
+        content += c.dim('  ─────────────────────────────────────────────────────\n');
+        content += '\n';
+
+        // Track table
+        const headers = ['', '#', 'Title', 'Artist', 'Time'];
+        const rows = items.map((track, i) => [
+            checked.has(i) ? c.green('x') : c.dim('-'),
+            c.dim(String(i + 1).padStart(2)),
+            truncate(track.title, 28),
+            truncate(track.artist, 18),
+            formatDuration(track.duration),
+        ]);
+
+        // Show a window of rows around the selected index (max ~15 visible)
+        const maxVisible = Math.min(15, process.stdout.rows - 12);
+        let startIdx = Math.max(0, selectedIdx - Math.floor(maxVisible / 2));
+        let endIdx = Math.min(rows.length, startIdx + maxVisible);
+        if (endIdx - startIdx < maxVisible) {
+            startIdx = Math.max(0, endIdx - maxVisible);
+        }
+
+        const visibleRows = rows.slice(startIdx, endIdx);
+        const adjustedSelected = selectedIdx - startIdx;
+
+        content += drawTable(headers, visibleRows, {
+            selected: adjustedSelected,
+            checked: new Set(
+                [...checked].filter(i => i >= startIdx && i < endIdx).map(i => i - startIdx)
+            ),
+        });
+
+        content += '\n\n';
+
+        // Status bar
+        const selectedCount = checked.size;
+        const bar = `  ${c.brightCyan(`${selectedCount}`)}/${tracks.length} selected`;
+        const scroll = rows.length > maxVisible
+            ? c.dim(`  |  ${startIdx + 1}-${endIdx} of ${rows.length}`)
+            : '';
+        content += bar + scroll + '\n';
+
+        content += c.dim('  up/down navigate | Space toggle | A select all | Enter download | Esc back');
+
+        render(content);
+    });
+
+    if (!selectedSet) return null;
+
+    // Return selected tracks
+    return tracks.filter((_, i) => selectedSet.has(i));
+}

package/src/screens/URLInput.js

@@ -0,0 +1,41 @@
+import { render, c } from '../tui/renderer.js';
+import { textInput } from '../tui/input.js';
+import { parseSpotifyUrl } from '../services/spotify.js';
+
+/**
+ * Show the URL input screen with live validation
+ * @returns {Promise<string|null>} The entered URL, or null if cancelled
+ */
+export async function showURLInput(input) {
+    const url = await textInput(input, (text) => {
+        let content = '\n';
+        content += c.brightCyan('  Paste a Spotify URL\n\n');
+
+        // URL input with live validation indicator
+        const parsed = text.trim() ? parseSpotifyUrl(text.trim()) : null;
+        const cursor = c.dim('|');
+
+        if (!text.trim()) {
+            content += c.dim('  > ') + cursor + '\n';
+            content += '\n';
+            content += c.dim('  Supported:\n');
+            content += c.dim('    open.spotify.com/track/...\n');
+            content += c.dim('    open.spotify.com/album/...\n');
+            content += c.dim('    open.spotify.com/playlist/...\n');
+        } else if (parsed) {
+            const typeLabel = parsed.type.charAt(0).toUpperCase() + parsed.type.slice(1);
+            content += c.green('  > ') + `${text}${cursor}\n`;
+            content += '\n';
+            content += c.green(`  Valid ${typeLabel} URL detected\n`);
+        } else {
+            content += c.red('  > ') + `${text}${cursor}\n`;
+            content += '\n';
+            content += c.red('  Not a valid Spotify URL\n');
+        }
+
+        content += '\n' + c.dim('  Enter continue | Esc back');
+        render(content);
+    });
+
+    return url && url.trim() ? url.trim() : null;
+}

package/src/screens/Welcome.js

@@ -0,0 +1,62 @@
+import { render, c } from '../tui/renderer.js';
+import { menuSelect } from '../tui/input.js';
+import { APP_VERSION } from '../constants.js';
+
+const BANNER = [
+    '  ███████╗███████╗██████╗ ██╗     ',
+    '  ██╔════╝██╔════╝██╔══██╗██║     ',
+    '  ███████╗███████╗██║  ██║██║     ',
+    '  ╚════██║╚════██║██║  ██║██║     ',
+    '  ███████║███████║██████╔╝███████╗',
+    '  ╚══════╝╚══════╝╚═════╝ ╚══════╝',
+];
+
+const MENU_ITEMS = [
+    { label: 'Paste a Spotify URL (track/playlist/album)', value: 'url' },
+    { label: 'Search for a song', value: 'search' },
+    { label: 'Settings', value: 'settings' },
+    { label: 'Exit', value: 'exit' },
+];
+
+/**
+ * Show the welcome screen with main menu
+ * @returns {Promise<string>} Selected action: 'url' | 'search' | 'settings' | 'exit'
+ */
+export async function showWelcome(input) {
+    const selectedIdx = await menuSelect(MENU_ITEMS, input, (items, selected) => {
+        let content = '\n';
+
+        // Banner with gradient
+        const grad = [
+            '\x1b[38;5;43m',   // teal
+            '\x1b[38;5;44m',   // cyan
+            '\x1b[38;5;45m',   // bright cyan
+            '\x1b[38;5;44m',   // cyan
+            '\x1b[38;5;43m',   // teal
+            '\x1b[38;5;42m',   // green-teal
+        ];
+        const reset = '\x1b[0m';
+
+        content += BANNER.map((line, i) => `${grad[i]}${line}${reset}`).join('\n');
+        content += '\n';
+        content += c.dim('  Spotify Song Downloader') + c.dim(`${' '.repeat(10)}v${APP_VERSION}`) + '\n';
+        content += c.dim('  ────────────────────────────────────') + '\n\n';
+
+        items.forEach((item, i) => {
+            const prefix = i === selected
+                ? c.brightCyan('  > ')
+                : '    ';
+            const label = i === selected
+                ? c.brightWhite(item.label)
+                : c.dim(item.label);
+            content += `${prefix}${label}\n`;
+        });
+
+        content += '\n' + c.dim('  up/down navigate | Enter select | Ctrl+C quit');
+
+        render(content);
+    });
+
+    if (selectedIdx === -1) return 'exit';
+    return MENU_ITEMS[selectedIdx].value;
+}

package/src/services/downloader.js

@@ -0,0 +1,93 @@
+import { spawn } from 'child_process';
+import { existsSync, mkdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { sanitizeFilename } from '../utils/format.js';
+
+/**
+ * Download a track from YouTube using yt-dlp
+ * @param {string} youtubeUrl - YouTube video URL
+ * @param {object} trackInfo - Track metadata { title, artist }
+ * @param {string} outputDir - Directory to save the file
+ * @param {function} onProgress - Callback with (percent, status)
+ * @returns {Promise<string>} - Path to the downloaded file
+ */
+export async function downloadTrack(youtubeUrl, trackInfo, outputDir, onProgress) {
+    // Ensure output directory exists
+    if (!existsSync(outputDir)) {
+        mkdirSync(outputDir, { recursive: true });
+    }
+
+    const filename = sanitizeFilename(`${trackInfo.title} — ${trackInfo.artist}`);
+    const outputPath = join(outputDir, `${filename}.%(ext)s`);
+    const expectedPath = join(outputDir, `${filename}.mp3`);
+
+    return new Promise((resolve, reject) => {
+        const args = [
+            youtubeUrl,
+            '--extract-audio',
+            '--audio-format', 'mp3',
+            '--audio-quality', '0',           // Best quality
+            '--output', outputPath,
+            '--no-playlist',
+            '--no-warnings',
+            '--progress',
+            '--newline',                       // Each progress update on a new line
+            '--no-check-certificates',
+        ];
+
+        const proc = spawn('yt-dlp', args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+
+        let lastPercent = 0;
+        let stderr = '';
+
+        proc.stdout.on('data', (data) => {
+            const lines = data.toString().split('\n');
+            for (const line of lines) {
+                // Parse progress lines like: [download]  45.2% of  4.81MiB at  1.23MiB/s ETA 00:03
+                const progressMatch = line.match(/\[download\]\s+([\d.]+)%/);
+                if (progressMatch) {
+                    const percent = parseFloat(progressMatch[1]);
+                    if (percent > lastPercent) {
+                        lastPercent = percent;
+                        if (onProgress) onProgress(percent, 'Downloading...');
+                    }
+                }
+
+                // Post-processing indication
+                if (line.includes('[ExtractAudio]') || line.includes('Post-process')) {
+                    if (onProgress) onProgress(lastPercent, 'Converting...');
+                }
+            }
+        });
+
+        proc.stderr.on('data', (data) => {
+            stderr += data.toString();
+        });
+
+        proc.on('close', (code) => {
+            if (code === 0) {
+                if (onProgress) onProgress(100, 'Done');
+                resolve(expectedPath);
+            } else {
+                reject(new Error(`yt-dlp exited with code ${code}: ${stderr}`));
+            }
+        });
+
+        proc.on('error', (err) => {
+            reject(new Error(`Failed to spawn yt-dlp: ${err.message}`));
+        });
+    });
+}
+
+/**
+ * Get the file size of a downloaded file
+ */
+export function getFileSize(filePath) {
+    try {
+        return statSync(filePath).size;
+    } catch {
+        return 0;
+    }
+}

package/src/services/metadata.js

@@ -0,0 +1,48 @@
+import NodeID3 from 'node-id3';
+
+/**
+ * Embed metadata (ID3 tags) into an MP3 file
+ * @param {string} filePath - Path to the MP3 file
+ * @param {object} meta - Track metadata
+ * @param {string} meta.title - Track title
+ * @param {string} meta.artist - Artist name
+ * @param {string} meta.album - Album name
+ * @param {string} [meta.artworkUrl] - URL to album artwork
+ * @param {number} [meta.trackNumber] - Track number
+ * @param {string} [meta.releaseDate] - Release date
+ */
+export async function embedMetadata(filePath, meta) {
+    const tags = {
+        title: meta.title,
+        artist: meta.artist,
+        album: meta.album,
+        trackNumber: meta.trackNumber ? String(meta.trackNumber) : undefined,
+        year: meta.releaseDate ? meta.releaseDate.split('-')[0] : undefined,
+    };
+
+    // Download and embed album artwork
+    if (meta.artworkUrl) {
+        try {
+            const artworkRes = await fetch(meta.artworkUrl);
+            if (artworkRes.ok) {
+                const buffer = Buffer.from(await artworkRes.arrayBuffer());
+                tags.image = {
+                    mime: 'image/jpeg',
+                    type: { id: 3, name: 'front cover' },
+                    description: 'Album Artwork',
+                    imageBuffer: buffer,
+                };
+            }
+        } catch {
+            // Skip artwork if download fails — not critical
+        }
+    }
+
+    // Write tags to file
+    const success = NodeID3.write(tags, filePath);
+    if (!success) {
+        throw new Error(`Failed to write ID3 tags to ${filePath}`);
+    }
+
+    return true;
+}

package/src/services/spotify.js

@@ -0,0 +1,208 @@
+import { SPOTIFY_TOKEN_URL, SPOTIFY_API_BASE } from '../constants.js';
+
+let accessToken = null;
+let tokenExpiry = 0;
+
+/**
+ * Authenticate with Spotify using Client Credentials flow
+ */
+export async function authenticate(clientId, clientSecret) {
+    const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
+
+    const res = await fetch(SPOTIFY_TOKEN_URL, {
+        method: 'POST',
+        headers: {
+            'Authorization': `Basic ${credentials}`,
+            'Content-Type': 'application/x-www-form-urlencoded',
+        },
+        body: 'grant_type=client_credentials',
+    });
+
+    if (!res.ok) {
+        const err = await res.json().catch(() => ({}));
+        throw new Error(`Spotify auth failed: ${err.error_description || res.statusText}`);
+    }
+
+    const data = await res.json();
+    accessToken = data.access_token;
+    tokenExpiry = Date.now() + (data.expires_in * 1000) - 60000; // Refresh 1 min early
+
+    return accessToken;
+}
+
+/**
+ * Check if the current token is still valid
+ */
+export function isAuthenticated() {
+    return accessToken && Date.now() < tokenExpiry;
+}
+
+/**
+ * Make an authenticated request to the Spotify API
+ */
+async function spotifyFetch(endpoint) {
+    if (!accessToken) {
+        throw new Error('Not authenticated. Call authenticate() first.');
+    }
+
+    const res = await fetch(`${SPOTIFY_API_BASE}${endpoint}`, {
+        headers: {
+            'Authorization': `Bearer ${accessToken}`,
+        },
+    });
+
+    if (res.status === 401) {
+        throw new Error('Spotify token expired. Re-authenticate.');
+    }
+
+    if (!res.ok) {
+        throw new Error(`Spotify API error: ${res.status} ${res.statusText}`);
+    }
+
+    return res.json();
+}
+
+/**
+ * Parse a Spotify URL and extract type + ID
+ * Supports:
+ *   https://open.spotify.com/track/ID
+ *   https://open.spotify.com/album/ID
+ *   https://open.spotify.com/playlist/ID
+ *   spotify:track:ID
+ */
+export function parseSpotifyUrl(url) {
+    // Web URL format
+    const webMatch = url.match(
+        /open\.spotify\.com\/(track|album|playlist)\/([a-zA-Z0-9]+)/
+    );
+    if (webMatch) {
+        return { type: webMatch[1], id: webMatch[2] };
+    }
+
+    // URI format (spotify:track:ID)
+    const uriMatch = url.match(
+        /spotify:(track|album|playlist):([a-zA-Z0-9]+)/
+    );
+    if (uriMatch) {
+        return { type: uriMatch[1], id: uriMatch[2] };
+    }
+
+    return null;
+}
+
+/**
+ * Get a single track's metadata
+ */
+export async function getTrack(id) {
+    const data = await spotifyFetch(`/tracks/${id}`);
+
+    return {
+        id: data.id,
+        title: data.name,
+        artist: data.artists.map(a => a.name).join(', '),
+        album: data.album.name,
+        duration: data.duration_ms,
+        artworkUrl: data.album.images?.[0]?.url || null,
+        releaseDate: data.album.release_date,
+        trackNumber: data.track_number,
+        url: data.external_urls?.spotify,
+    };
+}
+
+/**
+ * Get a playlist's metadata and all tracks
+ */
+export async function getPlaylist(id) {
+    const data = await spotifyFetch(`/playlists/${id}`);
+
+    let tracks = data.tracks.items
+        .filter(item => item.track)
+        .map(item => ({
+            id: item.track.id,
+            title: item.track.name,
+            artist: item.track.artists.map(a => a.name).join(', '),
+            album: item.track.album.name,
+            duration: item.track.duration_ms,
+            artworkUrl: item.track.album.images?.[0]?.url || null,
+            releaseDate: item.track.album.release_date,
+            trackNumber: item.track.track_number,
+            url: item.track.external_urls?.spotify,
+        }));
+
+    // Handle pagination — playlists can have > 100 tracks
+    let next = data.tracks.next;
+    while (next) {
+        const nextUrl = next.replace(SPOTIFY_API_BASE, '');
+        const nextData = await spotifyFetch(nextUrl);
+        const moreTracks = nextData.items
+            .filter(item => item.track)
+            .map(item => ({
+                id: item.track.id,
+                title: item.track.name,
+                artist: item.track.artists.map(a => a.name).join(', '),
+                album: item.track.album.name,
+                duration: item.track.duration_ms,
+                artworkUrl: item.track.album.images?.[0]?.url || null,
+                releaseDate: item.track.album.release_date,
+                trackNumber: item.track.track_number,
+                url: item.track.external_urls?.spotify,
+            }));
+        tracks = tracks.concat(moreTracks);
+        next = nextData.next;
+    }
+
+    return {
+        name: data.name,
+        description: data.description,
+        owner: data.owner.display_name,
+        totalTracks: tracks.length,
+        artworkUrl: data.images?.[0]?.url || null,
+        tracks,
+    };
+}
+
+/**
+ * Get an album's metadata and all tracks
+ */
+export async function getAlbum(id) {
+    const data = await spotifyFetch(`/albums/${id}`);
+
+    const tracks = data.tracks.items.map(item => ({
+        id: item.id,
+        title: item.name,
+        artist: item.artists.map(a => a.name).join(', '),
+        album: data.name,
+        duration: item.duration_ms,
+        artworkUrl: data.images?.[0]?.url || null,
+        releaseDate: data.release_date,
+        trackNumber: item.track_number,
+        url: item.external_urls?.spotify,
+    }));
+
+    return {
+        name: data.name,
+        artist: data.artists.map(a => a.name).join(', '),
+        totalTracks: tracks.length,
+        releaseDate: data.release_date,
+        artworkUrl: data.images?.[0]?.url || null,
+        tracks,
+    };
+}
+
+/**
+ * Search Spotify for tracks
+ */
+export async function searchTracks(query, limit = 10) {
+    const encoded = encodeURIComponent(query);
+    const data = await spotifyFetch(`/search?q=${encoded}&type=track&limit=${limit}`);
+
+    return data.tracks.items.map(item => ({
+        id: item.id,
+        title: item.name,
+        artist: item.artists.map(a => a.name).join(', '),
+        album: item.album.name,
+        duration: item.duration_ms,
+        artworkUrl: item.album.images?.[0]?.url || null,
+        url: item.external_urls?.spotify,
+    }));
+}