unreleased-cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,31 @@
+MIT License
+
+Copyright (c) 2026 leanwrldd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+NOTE: The MIT license above applies to the source code of this project
+("unreleased"). Binary distributions (desktop installers) bundle third-party
+components under their own licenses - including FFmpeg, which is licensed under
+the GNU General Public License v3.0. See THIRD-PARTY-NOTICES.md for details and
+obligations. This project is a fan-made client and is not affiliated with,
+endorsed by, or connected to Juice WRLD, his estate, or any associated party;
+all music, artwork, names, and trademarks belong to their respective owners.

package/README.md

@@ -1,3 +1,200 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# unreleased-cli
+
+The site's terminal as a command-line shell. You can browse the Files tab's channels as a folder tree, read text files, search, and download straight to disk. It uses the same API as the site.
+
+```
+guest@unreleased:~/files/comp$ ls
+     <dir>  Compilation/
+     <dir>  Snippets/
+     ...
+guest@unreleased:~/files/comp$ get -o covers "Compilation/4. Cover Art"
+saved 44 files (25.9 MB) to covers
+```
+
+## Install
+
+From npm (any OS, Node 20 or newer):
+
+```
+npm install -g unreleased-cli
+```
+
+On Ubuntu (PPA, Node 18 or newer):
+
+```
+sudo add-apt-repository ppa:leanwrldd/unreleased-cli
+sudo apt install unreleased-cli
+```
+
+From source:
+
+```
+npm install
+npm run build
+npm link          # puts `unreleased` on your PATH
+```
+
+You can also run it without linking: `node dist/unreleased.mjs`. It needs Node 20 or newer and has no runtime dependencies. Playback also needs [mpv](https://mpv.io) (`winget install shinchiro.mpv`, `brew install mpv`, or your package manager).
+
+## Use
+
+| | |
+|---|---|
+| `unreleased` | Open the interactive shell. |
+| `unreleased ls Snippets` | Run one command and exit. The exit code is 1 if the command failed. A single quoted argument is a whole line: `unreleased "ls \| head 2"`. |
+| `unreleased < script.txt` | Run each line of a file. Lines starting with `#` are comments. |
+
+The shell starts in the main channel (`comp`). `cd /` lists every channel, and `cd` on its own takes you back.
+
+Commands (type `help <command>` in the shell for the details of each one):
+
+- **Files:** `cd`, `ls`, `pwd`, `lcd`, `get`, `cat`, `head`, `tail`, `wc`, `grep`, `locate`, `tree`, `du`
+- **Library:** `find`, `song`, `like`, `unlike`, `liked`, `playlists`, `playlist`, `stats`
+- **Player:** `play`, `pause`, `toggle`, `next`, `prev`, `seek`, `volume`, `speed`, `shuffle`, `repeat`, `queue`, `status`, `sleep`, `stop`
+- **People:** `user`, `lookup`
+- **Admin** (administrators only): `pending`, `proposals`, `comps`, `applications`, `inspect`, `approve`, `reject`, `reverse`, `users`, `sitebans`, `siteunban`
+- **Fun:** `neofetch`, `fortune`, `juicesay`, `matrix`, `visualizer`, `wordle`, `heardle`
+- **Settings:** `set`, `settings`, `termtheme`
+- **Shell:** `source`, `alias`, `unalias`, `history`, `echo`, `watch`, `full`, `date`, `clear`, `exit`, `help`
+- **Account:** `login`, `logout`, `whoami`, `version`
+
+Things that work the same as on the site:
+
+- Pipe output into `grep`, `head`, `tail`, `wc`, `sort`, `uniq` or `juicesay`. A `|` inside quotes stays part of the argument.
+- `!!`, `!N` and `!text` re-run earlier commands.
+- Ctrl+R searches your history, as in bash:
+  - Type to find the newest match, and press Ctrl+R again for older ones.
+  - Enter runs the match. Esc or an arrow key puts it on the line to edit.
+  - Ctrl+C gives up and leaves the line as it was.
+- `cd -` goes back to the previous folder.
+- `alias` saves shortcuts.
+- Tab completes command names and paths.
+- Ctrl+C cancels the running command.
+- `watch [-n seconds] <command>` re-runs a command on a refreshing screen, every 2 seconds unless `-n` says otherwise. Quote it if it has a pipe: `watch -n 5 "pending | head 3"`. `q` leaves.
+
+`get` saves into the current local folder. Use `lcd` to change that folder, or `get -o <dir>` for a single download. A folder keeps its structure on disk where the site would hand you a ZIP. Files that already exist are skipped unless you pass `-f`.
+
+## Library
+
+`find <title>` searches the songs and numbers the results. `liked` and `playlist show` number theirs too. A number then stands for that row in the next command: `song 2`, `like 2`, `playlist add Chill -- 2`.
+
+- `song <title | N>` shows a song's era, credits and dates, plus the `get` command that downloads its file.
+- `playlist` can show, create, delete, add and remove. A playlist can be named by a few letters of its title or by its number in `playlists`. Deleting asks first, or takes `-y`. Playing a playlist is left to the site, since the CLI has no player.
+- `stats [all | 7 | 30] [N]` charts your listening history the way the site does. It needs the whole song catalog (about 11 MB), so a slim copy is kept in `~/.unreleased/cache` for a day. `-r` reloads it.
+- `user <id>` works for anyone. `user <name>` needs an administrator account, because it searches the admin account list. The site finds people through chat, which the CLI doesn't have.
+- `lookup <text>` searches songs, your playlists, channels, commands and (for administrators) people at once.
+
+Playlists, likes and stats need you to be signed in.
+
+## Playback
+
+Music plays through a hidden mpv that the interactive shell starts the first time you play something.
+
+- `play <title | N>` plays a song by title, or by its number from the last list.
+- `play <file | folder>` plays something from the file tree. A folder queues the audio files directly inside it, and `play .` plays the folder you're in.
+- `playlist play <name>`, `playlist shuffle <name>`, `liked play` and `shuffle <era> [count]` replace the queue.
+- `queue add` and `queue next` add to it. `queue` lists it, and `remove N` / `jump N` change it.
+- Shuffle, repeat, previous and the end of the queue behave as they do on the site.
+- `status` (or `now`) shows the song, a progress bar, the settings and the queue.
+- `like` and `unlike` with no song act on the one playing.
+
+The music stops when you leave the shell, so `unreleased play …` on its own says to open the shell instead. If the shell is killed without a chance to stop mpv (for example the terminal window is closed), mpv quits by itself within about 10 seconds.
+
+The CLI looks for mpv on PATH and then in the usual install folders. Set `UNRELEASED_MPV` to its path if it lives somewhere else. mpv reads your own `mpv.conf`, so settings like the audio device carry over.
+
+When you're signed in, a song counts as played once you've listened to it: 30 seconds in, or halfway through anything shorter, the same rule as the site's player. The play is added to your listening history on the site (`POST /accounts/account/me/listening-plays/`), so it shows up in `stats`, Home and your profile. Skipping through a queue doesn't count, and a song you restart or seek back to the start of can count again. Files played from the tree have no song id and never count. If the server refuses a play, the shell says so once.
+
+The song's play counter in your profile goes up by one as well. The server has no increment for it (the counters are one JSON blob the client replaces whole), so the CLI reads the blob, adds the plays and writes it back, keeping every other field as it was. That write waits a few seconds so a run of plays becomes one write, and the shell sends any that are left when you exit. If the shell is killed instead (the terminal window is closed), the last few seconds of counts are lost, but the history entries are not. The site merges counters with max(), so a count raised here isn't undone by a stale copy there.
+
+## Admin
+
+These cover the Admin page's review queues and site moderation, using the same endpoints. They only appear in `help` for an administrator account, and they stop any other account before a request is sent. If your role changed since you logged in, run `whoami` to refresh it.
+
+- `pending` shows how much is waiting in each queue.
+- `proposals`, `comps` and `applications` list a queue. Each takes a status: pending (the default), approved, rejected, or reversed.
+- `inspect [song|comp|app] <id>` shows one item in full. For a song edit, that's every field it changes.
+- `approve` and `reject` take `[song|comp|app] <id> [note]`. Song edits are the default kind, so `approve 12` and `reject 12 no source` work as they are.
+- `reverse [song|comp] <id>` undoes an approved proposal.
+- `users [role] [filter]` lists accounts. `user <name>` shows one person.
+- `sitebans` lists active site-wide bans, mutes and timeouts. `siteunban <user | #id>` lifts them.
+
+`reverse` and `siteunban` ask before they act. Outside the interactive shell, such as in one-shot use or a script, they need `-y` instead.
+
+## Fun
+
+- `neofetch` shows system info with a logo.
+- `fortune` prints a random lyric line from a random song. Try `fortune | juicesay`.
+- `juicesay [text]` has a juice box say it.
+- `matrix` is digital rain. Any key leaves.
+- `visualizer` (or `viz`) is a live spectrum of the song that's playing. Any key leaves. mpv can't hand its audio over, so a second mpv decodes the same stream to a temp file and the bars come from that, which means the song is downloaded a second time while the screen is open.
+- `wordle [daily | unlimited]` is the song-title Wordle, using the site's own puzzle logic, so the daily puzzle is the same one. Type a title and press Enter. Esc leaves, and your progress is saved.
+- `heardle` gives practice rounds: Tab plays the clip, Enter guesses (an empty Enter skips), and ↑↓ picks a suggestion. The clip plays through its own mpv. Music that was playing gets paused, and `play` resumes it.
+
+`matrix`, `visualizer`, `wordle`, `heardle` and `watch` take over the whole terminal, then hand it back as it was. They need an interactive terminal, so they won't run from a pipe or a script.
+
+Wordle and Heardle keep their progress, streaks and song lists in `~/.unreleased/storage.json`. That's separate from your browser's, the same way two browsers are separate. They use the default game settings, because the settings you change on the site are stored in your browser.
+
+## Settings
+
+`settings` lists what you can change, and `set <setting> [value]` shows or changes one (`set volume 40`, `set shuffle toggle`; Tab completes the names and choices). They're kept in `~/.unreleased/settings.json`, so they carry over to the next session, and without the shell (`unreleased set volume 40`) the value is saved for next time. The site's Settings screen is mostly look and layout, so only the parts a command line has are here:
+
+| Setting | |
+|---|---|
+| `theme` | The terminal colour scheme, the same as `termtheme` |
+| `color` | Colour in the output (`NO_COLOR` turns it off too) |
+| `volume`, `speed`, `repeat`, `shuffle` | The player's modes. The `volume`, `speed`, `repeat` and `shuffle` commands change the same values, and they now stay put between sessions, as on the site |
+| `pitch-shift` | Let the pitch follow the speed (off keeps the pitch where it was) |
+
+`termtheme [name]` lists the colour schemes (the site's own list, so a new one there turns up here after the next sync and build) or switches to one. A scheme colours the prompt, messages, rain and visualizer in truecolor, and the default one uses your terminal's own palette. It can't change the terminal's background.
+
+`full` asks the terminal window to go fullscreen, and to leave again. It sends the xterm request for that, which many terminals ignore (Windows Terminal does), so F11 is the fallback.
+
+## Signing in
+
+You can browse the files without an account. To sign in:
+
+- `login` asks for your API token. On the site, open the terminal and type `token copy` to get it.
+- `login <username>` signs in with a username and password, and asks for a 2FA code if the account has one.
+
+`logout` only forgets the token on this computer. The token itself keeps working on the site.
+
+## API base and route rules
+
+`api` shows the current base. `api set <url>` moves everything to another API instance, and `api reset` goes back to the default.
+
+Route rules send one path prefix somewhere else on top of that, like the site's Settings: `api rule /cdn https://cdn.example.com/juicewrld`. The longest matching prefix wins. `api unrule /cdn` removes one. `UNRELEASED_API` still overrides the base.
+
+## Files and environment
+
+Everything is kept in `~/.unreleased`. Set `UNRELEASED_HOME` to use another folder.
+
+| File | Contents |
+|---|---|
+| `config.json` | The token and account name (owner-only permissions where the OS supports it), plus an optional `"api"` base URL and `"rules"` route rules (set both with the `api` command) |
+| `history` | Typed commands. Start a line with a space and it won't be saved. |
+| `aliases.json` | Your aliases |
+| `settings.json` | What `set` and `termtheme` change: theme, colour, volume, speed, repeat, shuffle, pitch-shift |
+| `storage.json` | Wordle and Heardle progress, streaks and their cached song lists |
+| `cache/catalog.json` | The song catalog `stats` and `shuffle <era>` use, refreshed daily |
+| `rc` | Commands run each time the interactive shell starts |
+
+| Environment variable | Effect |
+|---|---|
+| `UNRELEASED_TOKEN` | Use this token instead of the saved one |
+| `UNRELEASED_API` | Use another API base (the default is `https://juicewrldapi.com/juicewrld`) |
+| `UNRELEASED_MPV` | The mpv executable to play through |
+| `NO_COLOR` | Turn off colours |
+
+Git Bash on Windows rewrites a bare `/` argument into its own install path, so `unreleased ls /` lists the wrong place there. Run it from inside the shell, or set `MSYS_NO_PATHCONV=1`.
+
+## How it's built
+
+Some of the CLI is the site's own code, compiled in by `build.mjs`. That code lives in `site/`, a copy of the files from the site repo (kept in the same folder layout, so their imports still resolve). `site/SYNCED_FROM.json` says which site commit it was taken from, and `site-modules.mjs` lists which modules are used and which of their imports are swapped for a Node version:
+
+- `cat`, `head`, `tail`, `wc`, `grep`, `locate`, `tree` and `du` come from `src/renderer/src/lib/terminalFileTools.ts`. Its imports point at `src/files.ts`, the Node version of the site's `terminalFiles.ts`.
+- The `stats` maths comes from `lib/listeningStats.ts`. Its two helpers from `juicewrldApi.ts` are swapped for `src/shims/juicewrldApi.ts`.
+- Playlist name matching comes from `lib/terminal/types.ts`.
+- The `termtheme` colour schemes come from `lib/terminal/themeStore.ts` (its `react` import is swapped for a stub).
+- The Wordle and Heardle logic comes from `lib/wordle.ts`, `lib/heardle.ts` and `lib/versionsApi.ts`. That covers the daily pick, grading, title search and version matching. Their request helpers are swapped for shims in `src/shims/`, and `localStorage` for `src/shims/localStorage.ts`.
+
+A change to those on the site reaches the CLI when you run `npm run sync` (it copies the files from the site checkout next to this repo, `../music-player-web`; pass another path with `npm run sync -- <path>` or `UNRELEASED_SITE`) and then `npm run build`. The sync works out the file list itself by bundling against the checkout, so a new import in one of those modules is picked up without editing anything. The declarations in `src/site.d.ts` have to stay in step with their signatures. The other commands are ports, because their site versions read the app's stores.