@bzenky/spoti 0.1.0 → 0.3.0

package/README.md

@@ -21,13 +21,27 @@ Create an application in the [Spotify Developer Dashboard](https://developer.spo
 http://127.0.0.1:43821/callback
 ```
 
-Export the application's client ID before running authentication:
+After installing `spoti`, save the application's client ID once:
+
+```bash
+spoti setup
+spoti login
+```
+
+When developing from source, use:
+
+```bash
+npm run dev -- setup
+npm run dev -- login
+```
+
+The setup command stores the public client ID in your local `spoti` configuration. For temporary sessions, CI, or an explicit override, you can still use:
 
 ```bash
 export SPOTIFY_CLIENT_ID="your-client-id"
 ```
 
-To use a different local callback, register it in the same Spotify application and set:
+The environment variable takes precedence over the stored value. To use a different local callback, register it in the same Spotify application and set:
 
 ```bash
 export SPOTIFY_REDIRECT_URI="http://127.0.0.1:5000/callback"
@@ -78,12 +92,51 @@ Control playback:
 
 ```bash
 spoti now
+spoti now --watch
 spoti play "Numb"
 spoti play "Numb" --first
+spoti play "Numb" --watch
+spoti play "Numb" --no-watch
 spoti pause
 spoti resume
 spoti next
 spoti previous
+spoti volume 50
+spoti volume +10
+spoti volume -10
+spoti shuffle on
+spoti shuffle off
+spoti repeat off
+spoti repeat track
+spoti repeat context
+```
+
+Manage playback devices:
+
+```bash
+spoti devices
+spoti device 2
+spoti device "My Computer"
+```
+
+Use the displayed one-based number, exact device name, or Spotify device ID.
+
+When playback has no active device, `spoti play` and `spoti resume` automatically target it if exactly one controllable device is available.
+
+Seek within the current track:
+
+```bash
+spoti seek 1:30
+spoti seek +30
+spoti seek -10
+```
+
+View the queue or search for a track to add:
+
+```bash
+spoti queue
+spoti queue "Faint"
+spoti queue "Faint" --first
 ```
 
 Search without starting playback:
@@ -93,6 +146,49 @@ spoti search "Breaking the Habit"
 spoti search "Breaking the Habit" --limit 5
 ```
 
+Search, inspect, and play Spotify contexts:
+
+```bash
+spoti album "Meteora"
+spoti artist "Linkin Park"
+spoti playlists
+spoti playlist 1
+spoti playlist "Workout"
+spoti play track "Numb"
+spoti play album "Meteora"
+spoti play artist "Linkin Park"
+spoti play playlist "Workout"
+spoti play playlist 1
+```
+
+User playlists are sorted consistently by name, so the displayed number can be reused with `spoti playlist <number>` or `spoti play playlist <number>`.
+
+In an interactive terminal, `spoti album` can play the entire album or a selected track after showing its details. `spoti artist` can play the artist context or let you select one of the artist’s albums, and `spoti playlist` can start the selected playlist. Non-interactive runs remain display-only and never start playback implicitly.
+
+`spoti play <query>` remains shorthand for track playback. The words `track`, `album`, `artist`, and `playlist` are treated as explicit types when followed by another argument. For a track query that starts with one of those reserved words, use `spoti play track <query>` (or quote the complete query as one shell argument). Context commands support `--first` to skip interactive selection.
+
+Manage and inspect your Spotify library:
+
+```bash
+spoti liked
+spoti liked --limit 10
+spoti like
+spoti unlike
+spoti recent
+spoti recent --limit 10
+```
+
+`spoti like` and `spoti unlike` operate on the currently playing track. Episodes, advertisements, local files, and unavailable items are ignored safely.
+
+Check for updates or install the latest npm release:
+
+```bash
+spoti update --check
+spoti update
+```
+
+`spoti update` asks for confirmation before installing the exact version returned by the update check. It never installs an update silently. Normal commands use a cached update result and refresh it in a detached process at most once every 24 hours, so npm availability does not delay or break Spotify controls.
+
 Remove local credentials:
 
 ```bash
@@ -101,6 +197,37 @@ spoti logout
 
 When attached to an interactive terminal, `spoti play <query>` asks you to select a result. In non-interactive usage it chooses the first result automatically; `--first` makes that behavior explicit.
 
+Watch mode continuously refreshes the current track and progress until `Ctrl+C` is pressed. `--watch` enables it for one command, while `--no-watch` overrides a saved preference.
+
+## Configuration
+
+View all settings:
+
+```bash
+spoti config
+```
+
+Read, update, or reset settings:
+
+```bash
+spoti config get spotifyClientId
+spoti config set spotifyClientId "your-client-id"
+spoti config get watchAfterPlay
+spoti config set watchAfterPlay true
+spoti config set refreshIntervalMs 2000
+spoti config reset
+```
+
+Available settings:
+
+| Setting | Default | Description |
+| --- | ---: | --- |
+| `spotifyClientId` | `null` | Public Spotify application client ID saved by `spoti setup`. |
+| `watchAfterPlay` | `false` | Keep `spoti play` open in watch mode after playback starts. |
+| `refreshIntervalMs` | `1000` | Watch refresh interval from `1000` to `30000` milliseconds. |
+
+Command flags take precedence over saved configuration. Application preferences are stored in `$XDG_CONFIG_HOME/spoti/config.json`, or `~/.config/spoti/config.json` when `XDG_CONFIG_HOME` is not set.
+
 ## Credentials
 
 Credentials are stored locally in:
@@ -115,7 +242,7 @@ or, when `XDG_CONFIG_HOME` is not set:
 ~/.config/spoti/credentials.json
 ```
 
-The credentials file is created with user-only permissions (`0600`). Access tokens refresh automatically. Keep `SPOTIFY_CLIENT_ID` available in the environment because Spotify requires it during token refresh. Never provide or store a Spotify client secret in `spoti`.
+The credentials file is created with user-only permissions (`0600`). Access tokens refresh automatically using the environment client ID when present, otherwise the client ID saved by `spoti setup`. Version `0.3.0` adds minimum permissions for private playlist listing, liked-track access, library modification, and recently played tracks. Existing installations will be asked to run `spoti login` once after upgrading. Never provide or store a Spotify client secret in `spoti`.
 
 ## Spotify API policy
 
@@ -132,6 +259,19 @@ npm test
 npm run build
 ```
 
+## Releases
+
+GitHub Releases are created automatically when a version tag is pushed. The tag must match the version in `package.json`:
+
+```bash
+npm version patch
+npm run verify
+git push origin main
+git push origin v0.1.1
+```
+
+The release workflow attaches the npm package tarball and a `SHA256SUMS` file, and generates release notes from the Git history. Publishing to npm remains a separate explicit step.
+
 ## Current scope
 
-Version `0.1.0` supports authentication, current playback, track search, direct track playback, pause/resume, and next/previous controls. Queue, volume, seek, shuffle, repeat, device switching, library features, JSON output, and a TUI are planned for later releases.
+Version `0.3.0` supports authentication and persistent client-ID setup; track, album, artist, and playlist discovery and playback; guided playback actions; current playback and watch mode; pause/resume and next/previous; volume, seek, shuffle, and repeat; queue and library management; recently played tracks; deterministic numeric device and playlist selection; and cached update notifications with explicit update commands. JSON output and a TUI remain planned for later releases.

package/dist/app.d.ts

@@ -1,14 +1,40 @@
 import { Command } from 'commander';
 import type { AuthService } from './services/auth.service.js';
+import type { CatalogService } from './services/catalog.service.js';
+import type { DeviceService } from './services/device.service.js';
+import type { LibraryService } from './services/library.service.js';
 import type { PlayerService } from './services/player.service.js';
+import type { PlaylistService } from './services/playlist.service.js';
+import type { QueueService } from './services/queue.service.js';
+import type { RecentService } from './services/recent.service.js';
 import type { SearchService } from './services/search.service.js';
+import { type UpdateService } from './services/update.service.js';
+import { type ConfigStore } from './storage/config.js';
 import { type Output } from './ui/output.js';
-import { selectTrack } from './ui/prompts.js';
+import { confirmUpdate, promptSpotifyClientId, selectAlbum, selectAlbumAction, selectArtist, selectArtistAction, selectPlaylist, selectPlaylistAction, selectTrack } from './ui/prompts.js';
+import { type PlaybackWatcher } from './ui/watch.js';
 export interface AppDependencies {
     auth: AuthService;
+    catalog: CatalogService;
     player: PlayerService;
     search: SearchService;
+    playlist: PlaylistService;
+    library: LibraryService;
+    recent: RecentService;
+    device: DeviceService;
+    queue: QueueService;
+    update: UpdateService;
+    config: ConfigStore;
     output: Output;
     chooseTrack?: typeof selectTrack;
+    chooseAlbum?: typeof selectAlbum;
+    chooseArtist?: typeof selectArtist;
+    choosePlaylist?: typeof selectPlaylist;
+    chooseAlbumAction?: typeof selectAlbumAction;
+    chooseArtistAction?: typeof selectArtistAction;
+    choosePlaylistAction?: typeof selectPlaylistAction;
+    requestSpotifyClientId?: typeof promptSpotifyClientId;
+    confirmUpdate?: typeof confirmUpdate;
+    watchPlayback?: PlaybackWatcher;
 }
 export declare function createProgram(dependencies: AppDependencies): Command;