Release 0.2.2

Author: Ciphore

.github/workflows/ci.yml

@@ -21,6 +21,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     timeout-minutes: 25
     strategy:
+      fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
         node-version: [22.x, 24.x]
@@ -38,7 +39,7 @@ jobs:
         run: npm ci
 
       - name: Audit required runtime dependencies
-        run: npm audit --omit=dev --omit=optional --audit-level=high
+        run: npm run audit:runtime
 
       - name: Typecheck
         run: npm run check
@@ -72,6 +73,7 @@ jobs:
     if: github.event_name != 'pull_request'
     timeout-minutes: 15
     strategy:
+      fail-fast: false
       matrix:
         node-version: [22.x, 24.x]
     steps:
@@ -98,6 +100,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 20
     strategy:
+      fail-fast: false
       matrix:
         node-version: [22.x, 24.x]
     steps:
@@ -117,7 +120,7 @@ jobs:
 
       - name: Audit production dependencies
         working-directory: apps/docs
-        run: npm audit --omit=dev --audit-level=high
+        run: node ../../scripts/audit-ci.mjs --omit=dev --audit-level=high
 
       - name: Typecheck
         working-directory: apps/docs

CHANGELOG.md

@@ -7,6 +7,91 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-09-04
+
+### Added
+
+- Added one-time and IANA-timezone recurring radio alarms under Overview, with a
+  full-screen TUI editor, station picker, next-run preview, enable/disable,
+  delete confirmation, test tune, repair, and active ringing controls.
+- Added native background registration through macOS launchd, Windows Task
+  Scheduler, and systemd user timers on Linux, plus `radiocli alarm` commands
+  for scripting, inspection, health checks, synchronization, and playback
+  control.
+- Added optional per-alarm wake requests where the OS supports them and a
+  separate cross-platform Alarm Guard that prevents idle sleep until the next
+  occurrence.
+- Added automatic ringing-control launch in the terminal captured when an alarm
+  is synchronized, with reuse of an already-running RadioCLI TUI.
+- Added a navigable **Verify alarm setup** rehearsal that exercises a disposable
+  native job, the saved terminal, authenticated controls, sleep protection,
+  system volume, and a three-second configured-station sample before cleanup.
+- Added `radiocli setup`, an interactive installer that detects supported
+  package managers, previews required playback tools, supports dry runs, guides
+  installation, and verifies the resulting local playback configuration.
+- Added an adaptive Explore experience with a responsive Cosmo world map,
+  height-aware station lists in micro terminals, pointer-accurate map
+  selection, and safe scrolling marquees for long station details.
+- Added richer `radiocli doctor` playback diagnostics, including the resolved
+  mpv path, discovery source, launchability, version output, and actionable
+  launch errors. Windows discovery now covers package-manager shims, common
+  application directories, and registered mpv installations.
+
+### Changed
+
+- Full library backup and restore now carries alarm definitions and latest run outcomes;
+  native jobs, Alarm Guard state, runtime health, and local control credentials
+  remain specific to each machine and are rebuilt by alarm synchronization.
+- macOS terminal Automation permission is requested during alarm setup, and a
+  TUI opened by a ringing alarm now protects the active native job from startup,
+  repair, edit, and delete reconciliation until playback ends.
+- Snooze now closes the completed ringing session, returns to Alarms, and shows
+  the next ring time. Alarm playback temporarily unmutes and raises a low local
+  system output to the configured alarm level on macOS, Windows, and supported
+  Linux audio stacks, restoring the previous state afterward.
+- Alarm list and editor presentation is more concise: historical dismissal text,
+  duplicated controls, and long scheduler caveats were removed; specific field
+  guidance is now inline and Save is presented as a display-color action.
+- Alarm ringing controls now use Enter to transfer the station into normal
+  interactive playback and Space to stop and snooze for ten minutes. The alarm
+  UI and documentation identify scheduling as experimental beta functionality,
+  explain when the terminal may close, and recommend a secondary device for
+  critical wake-ups.
+- Playback-backend guidance now directs users to `radiocli setup` when local
+  tools are missing, with updated CLI help, setup documentation, and status
+  messages covering the guided workflow.
+- Receiver animation updates are isolated from the rest of the application,
+  respect reduced-motion preferences, and use cached visualizer geometry and
+  compact color runs to reduce rendering work without changing visual output.
+- Radio Browser requests now use atlas-aware timeouts and retain clearer
+  provider failure details when station directories are slow or unavailable.
+
+### Fixed
+
+- Alarm lists now scroll long text only on the focused interactive row, keep
+  selection and enabled-state markers fixed, and avoid repeating station and
+  next-run details. Compact and micro layouts use shorter next-wake, scheduler,
+  and beta-safety messages instead of clipping desktop-length copy.
+- Footer shortcut legends now balance actions across every available row,
+  reserve an additional row in compact terminals when space permits, and show
+  concise key-only hints in micro layouts instead of ending in truncated text.
+  The version and update indicator remains independently anchored at bottom right.
+- Rapid keyboard and mouse-wheel navigation now commits the selected row
+  immediately, cancels pending automatic station skips, and preserves alarm
+  editor scrolling; search input keeps ownership of typed alarm-shortcut
+  characters.
+- Player shutdown now coalesces concurrent stop requests, while delayed
+  automatic skipping can be canceled during retuning to avoid duplicate
+  process termination and unintended station changes.
+- Explore maps, station lists, and screen rendering now remain aligned and
+  navigable across compact and true-micro terminal sizes, with improved map
+  centering, cursor mapping, and visible provider errors.
+
+### Security
+
+- Active alarm controls and Alarm Guard ownership checks use authenticated
+  loopback-only endpoints with machine-local private token files.
+
 ## [0.2.1] - 2026-08-22
 
 ### Added
@@ -265,6 +350,7 @@ Initial public release.
 [0.1.9]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.9
 [0.2.0]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.0
 [0.2.1]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.1
+[0.2.2]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.2
 [0.1.4]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.4
 [0.1.3]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.3
 [0.1.2]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.2

README.md

@@ -18,9 +18,11 @@ Built with [Ink](https://github.com/vadimdemedes/ink),
 - Discover stations through Explore, Search, Countries, or approximate-location Nearby.
 - Listen with a receiver-style Now Playing screen, live metadata, sleep timer, diagnostics, and selectable visualizers.
 - Keep favorites, recents, imports, track history, and listening stats on your machine.
+- Create one-time or recurring radio alarms from the TUI, with native background
+  scheduling, station fallback, missed-run grace, snooze, and optional Alarm Guard.
 - Move through the exact station list you tuned from with previous and next controls.
 - Use `mpv` for complete playback control, with `ffplay` and VLC as limited fallbacks.
-- Resize freely: full, compact, and micro layouts preserve navigation and essential controls.
+- Resize freely: full, compact, and micro layouts preserve navigation and essential controls; Explore retains its interactive world map at every usable size.
 
 ## Quick start
 
@@ -35,13 +37,14 @@ macOS, Linux, or Windows with npm:
 
 ```bash
 npm install -g @ciphore/radiocli
-radiocli doctor
+radiocli setup
 radiocli
 ```
 
 RadioCLI requires Node.js 22 or newer. The Homebrew formula installs `mpv` and
-FFmpeg; npm installs JavaScript dependencies only, so install `mpv` with your
-system package manager for pause, volume, mute, media keys, and metadata.
+FFmpeg. After an npm install, `radiocli setup` detects the operating system and
+package manager, lets you choose `mpv`, FFmpeg, and VLC, installs the selected
+native tools with branded progress feedback, and verifies playback readiness.
 
 See the [installation guide](apps/docs/content/docs/getting-started/install.mdx)
 for Windows, Linux distributions, AirPlay prerequisites, and fallback players.
@@ -100,11 +103,34 @@ radiocli countries
 radiocli import stations.m3u
 radiocli export favorites.m3u
 radiocli add-url <stream-url> [station name]
+radiocli alarm list
+radiocli alarm doctor
 ```
 
 RadioCLI imports `.m3u`, `.pls`, and `.xspf` playlists. It exports favorites
 and imported streams as `.m3u`.
 
+Alarms are experimental beta functionality and live under **Overview**,
+immediately before Settings. Saving an enabled
+alarm registers it with launchd on macOS, a systemd user timer on Linux, or Task
+Scheduler on Windows, so the terminal does not need to remain open. When it
+fires, RadioCLI reopens the saved supported terminal and shows the ringing
+screen. Enter transfers the station into normal interactive playback; Space
+stops it and snoozes for 10 minutes. If a
+RadioCLI TUI is already open, that instance shows the controls instead. The
+computer must still be powered on with a logged-in interactive audio session; wake timing
+depends on hardware and OS power policy. See the [CLI guide](apps/docs/content/docs/getting-started/cli.mdx)
+and [reliability notes](apps/docs/content/docs/reliability.mdx) before relying on
+an alarm for something critical. Use a secondary device as the primary alarm
+for safety-critical, medical, travel, or emergency timing. See the dedicated
+[Alarms guide](apps/docs/content/docs/alarms.mdx) for the full workflow.
+
+The **Verify alarm setup** row performs a disposable native-scheduler
+registration, an authenticated terminal/control handshake, sleep-inhibitor and
+system-volume checks, and a short sample from the next configured alarm. It
+cleans up the temporary job and reports hard blockers separately from hardware-
+or policy-dependent wake limitations.
+
 See the [CLI guide](apps/docs/content/docs/getting-started/cli.mdx) for all
 arguments and examples.
 
@@ -120,14 +146,27 @@ Playback waits for backend readiness, applies tune timeouts, and can skip broken
 streams. Corrupt library and cache files are backed up instead of silently
 overwritten.
 
+Scheduled playback retries the primary station once, then tries an optional
+fallback. A missed-run grace window controls catch-up after sleep or logout.
+True fade-in requires `mpv`; `ffplay` and VLC start audibly at the configured
+target volume. Scheduled alarms always use local speakers, never unattended
+AirPlay.
+
+On macOS, an npm or source installation is executed by Node, so System Settings
+may identify its background item as `node`. Showing RadioCLI as the providing
+application requires a future signed macOS app bundle with a bundled helper;
+changing a launchd label cannot safely relabel the executable.
+
 Read the [reliability notes](apps/docs/content/docs/reliability.mdx) for failure
 handling and troubleshooting.
 
 ## Privacy
 
 RadioCLI does not require an account, proxy audio, or upload your listening
-history. Favorites, recents, imports, settings, track history, and activity stay
-in a local JSON library.
+history. Favorites, recents, imports, settings, alarms, track history, and
+activity stay in a local JSON library. Full JSON library backups include alarm
+definitions, while native scheduler registrations, runtime health, Alarm Guard
+state, and authenticated loopback-control tokens remain machine-local.
 
 Nearby contacts `ipapi.co` only when you open that screen, then uses an
 approximate location to sort the local station atlas. Disable the lookup with
@@ -145,6 +184,7 @@ complete data-flow description.
 - `src/ui` — screens, input, layout, and terminal rendering
 - `src/providers` — station directories, resolution, and caches
 - `src/player` — playback backends, metadata, and AirPlay
+- `src/alarms` — schedules, native registration, Alarm Guard, and active controls
 - `src/storage` — local library persistence and migration
 - `apps/docs` — documentation website and manual
 

apps/docs/app/(home)/page.tsx

@@ -111,7 +111,11 @@ export default function HomePage() {
                 <span className="rc-install-label">Universal · npm</span>
                 <p className="rc-install">
                   <span className="rc-prompt">$</span>
-                  <code>npm install -g @ciphore/radiocli</code>
+                  <code>
+                    npm install -g @ciphore/radiocli
+                    <br />
+                    radiocli setup
+                  </code>
                 </p>
               </div>
               <div className="rc-install-option">

apps/docs/app/llms.mdx/route.ts

@@ -15,6 +15,7 @@ With npm:
 
 \`\`\`bash
 npm install -g @ciphore/radiocli
+radiocli setup
 \`\`\`
 
 On macOS with Homebrew:

apps/docs/content/docs/alarms.mdx

@@ -0,0 +1,99 @@
+---
+title: Alarms (Beta)
+description: Create, verify, and troubleshoot scheduled radio alarms across macOS, Windows, and Linux.
+---
+
+# Alarms (Beta)
+
+RadioCLI alarms are experimental. They are designed for wake-to-radio and
+scheduled listening, but hardware, operating-system power policy, login state,
+audio devices, and live-stream availability can still prevent sound. Use a
+secondary device as the primary alarm for critical, medical, travel, or
+emergency timing.
+
+## Create An Alarm
+
+Open **Overview → Alarms (beta)** and choose **Create alarm**, or press `n`.
+Pressing `a` on a selected or playing station opens the same editor with that
+station filled in.
+
+The editor includes:
+
+- a one-time date or recurring weekday schedule with an explicit IANA timezone
+- segmented hour/minute controls and a Monday-through-Sunday checklist
+- primary and fallback stations from current playback, favorites, imports,
+  recents, and existing alarms
+- alarm volume, mpv fade-in, automatic stop time, and local-speaker output
+- missed-run grace, a best-effort OS wake request, and optional Alarm Guard
+- a station test tune, next-occurrence preview, Save, and Cancel
+
+Saving is local-first. An enabled alarm also registers its next occurrence with
+launchd on macOS, Task Scheduler on Windows, or a systemd user timer on Linux.
+After successful registration, the terminal does not need to remain open.
+
+## Verify The Complete Setup
+
+Choose **Verify alarm setup** at the bottom of the alarm list. Verification
+rehearses a disposable native job, terminal launch and authenticated controls,
+sleep protection, system-volume handling, and a short sample from the next
+configured alarm. It removes temporary artifacts before reporting success.
+
+Run Verify after creating the first alarm and whenever the terminal app,
+playback backend, audio device, installation path, OS permissions, timezone, or
+power settings change. A successful rehearsal proves that the tested path works
+now; it cannot guarantee future hardware wake, network access, or stream health.
+
+## When The Alarm Rings
+
+RadioCLI starts the configured station through a detached runner. If necessary,
+it opens the terminal captured during setup and shows the ringing screen.
+
+- `Enter` transfers the station into the interactive RadioCLI player and opens
+  the normal Playing screen. The visualizer and ordinary playback controls then
+  own the stream, and the alarm session ends.
+- `Space` stops the station and snoozes the alarm for 10 minutes.
+- `Up` and `Down` choose an exact occurrence when multiple alarms overlap.
+- `b` returns to the app while the detached alarm continues playing. Press `!`
+  from any screen to reopen its controls.
+
+The runner raises and unmutes supported local system output when it is below the
+configured alarm volume. During an interactive handoff, that audible level is
+preserved for regular playback. Scheduled alarms use local speakers; unattended
+AirPlay is not supported.
+
+## Background Delivery And Power
+
+All platforms require a powered-on machine, a logged-in interactive audio
+session, usable local speakers, and a reachable station. Windows can request
+`WakeToRun`; launchd and systemd user scheduling can catch up after wake or
+session resume. Exact wake still depends on hardware, firmware, lid, battery,
+hibernate, and administrator policy.
+
+Alarm Guard is separate from the scheduler wake request. It prevents ordinary
+idle sleep until the next occurrence using `caffeinate`, `systemd-inhibit`, or
+Windows execution-state APIs. It consumes power and cannot override shutdown,
+hibernate, explicit sleep, a closed lid, logout, or enforced OS policy.
+
+See [Reliability](./reliability.mdx) for the platform matrix, permission flow,
+timezone and DST semantics, fallback behavior, volume integration, and known
+limitations.
+
+## Diagnose And Repair
+
+From the alarm list, press `r` to repair native registrations or select
+**Verify alarm setup** for a full rehearsal. The CLI provides deeper status:
+
+```bash
+radiocli alarm doctor
+radiocli alarm status
+radiocli alarm sync
+radiocli alarm test ALARM_ID
+```
+
+Run `sync` after moving the RadioCLI installation, restoring a backup, changing
+the host timezone, or repairing scheduler files. See [CLI usage](./getting-started/cli.mdx)
+for alarm creation, editing, selectors, and JSON status output.
+
+Alarm definitions are included in full local-library backups. Native scheduler
+jobs, active control tokens, Guard processes, and machine health are deliberately
+not portable and must be recreated with `radiocli alarm sync` on the destination.