Appendix P: NightGard Library Commander (Shop Manual)

Status: v1.0 pre-release. In development; must reach Mac App Store before book release per project memory. Sandboxed for Mac App Store distribution — the sandboxing is load-bearing and is not to be removed. GPL v3. Locked as CryoTunes companion supplemental in the book's appendix slot. Public repo at github.com/fluhartyml/NightGard-Library-Commander. NightGard Library Commander is a Mac-only Apple Music library organization tool for users whose library has grown messy over the years — missing metadata, orphan playlists, uploaded-but-unmatched tracks, broken cloud status. The app cleans at the library level (MusicKit + AppleScript-on-macOS), never by moving physical audio files. Its sibling NightGard Commander handles the file-level work.

What it is

The project's reference audit at start named the problem precisely: 27,255 tracks across 45 playlists; 5,460 missing artist; 8,428 missing album; 7,226 missing genre; 11,247 matched; 3,122 subscription; 969 purchased; 6,651 uploaded; ~5,250 in problem cloud status. A long-tenured iCloud Music Library accumulates that kind of state, and Apple Music's own UI doesn't expose enough bulk tools to fix it. Library Commander is the bulk tool.

v1.0 ships four panes:

1. Playlists. List all user playlists, multi-select, bulk delete, rename in place, group into folders where supported.
2. Library. Filter to uploaded + problem-state tracks (the two pools that benefit from cleanup), per-row catalog search to find canonical Apple Music versions, one-tap replace.
3. Playlist Locker. Backup all playlists to dated folders in iCloud Documents, list existing backups, restore from M3U, delete backups.
4. Stats. Live library-health dashboard — tracks, playlists, missing fields, cloud status distribution.

Architecture overview

Mac SwiftUI app, sandboxed, with two service layers:

• App entry: NightGard_Library_CommanderApp.swift — @main scene.
• Root: ContentView.swift — NavigationSplitView shell with the four-pane sidebar.
• Panes (Views/):
  • PlaylistsPaneView.swift — user-playlist list with multi-select, bulk operations, in-place rename.
  • LibraryPaneView.swift — filtered track listing for uploaded + problem-state, with per-row catalog-search controls.
  • LockerPaneView.swift — the Playlist Locker UI (backup, list, restore, delete).
  • StatsPaneView.swift — library-health dashboard.
• Services (Services/):
  • LibraryService.swift — the MusicKit + AppleScript bridge. Reads the library via MusicLibraryRequest<Track> / MusicLibraryRequest<Playlist>; mutates via AppleScript-on-macOS where MusicKit's read-only or limited write surface doesn't cover the operation.
  • PlaylistLockerService.swift — ported from the earlier TngrnGrvWr project, Apple-Music-only variant. Handles snapshot serialization, iCloud Documents writes, and M3U restore.
• Notes: NightGard_Library_Commander_DeveloperNotes.swift — canonical reference with project audit numbers and the four-pane MVP roadmap.

Scope rules (the DRM line)

Library Commander touches only the parts of an Apple Music library that are safely mutable:

• Uploaded tracks — tracks the user added to iCloud Music Library from their own files. The user owns these; the app can replace them with canonical Apple Music versions when a match exists.
• Problem-state tracks — tracks Apple Music has flagged as "no longer available" or "error" in cloud status. These need user attention regardless; the app surfaces them in one place.

It does not touch:

• Matched tracks — Apple Music's canonical match for a previously-uploaded file. The matching is Apple's; the app respects it.
• Subscription tracks — tracks added from the Apple Music catalog while subscribed.
• Purchased tracks — iTunes-purchased tracks. DRM and licensing constraints rule these out.

The DRM line is conservative on purpose. Touching purchased or subscription tracks risks corrupting the user's library or running afoul of licensing; the app stays in the lane where edits are unambiguously safe.

The Playlist Locker

The Locker is the lowest-risk feature in the app: it never modifies the user's playlists, only snapshots them. Backups go to a dated folder in iCloud Documents (the app declares the iCloud Documents capability in its entitlements). Each backup is a set of .m3u files — one per playlist — with the canonical track identifiers preserved. Restore reads the M3U files back and recreates the playlists with the tracks in the same order.

Locker code is ported from an earlier project (TngrnGrvWr) and stripped to Apple-Music-only behavior. Cross-platform / non-Apple-Music sources aren't supported in v1.0.

The MusicKit + AppleScript split

Library Commander uses two Apple-provided surfaces because neither one alone covers the job:

• MusicKit — modern Swift API; great for reading the library (MusicLibraryRequest), reasonable for some writes. Apple's preferred path.
• AppleScript-on-macOS — older, but the only public surface for some library-level mutations that MusicKit doesn't expose. The Mac Music.app exposes a scripting dictionary; the app sends Apple events to it for those operations.

LibraryService picks the right tool per operation. The split is invisible to the panes — they call LibraryService.deletePlaylists(_:) or LibraryService.renamePlaylist(_:to:) and the service handles which mechanism to use.

Sandbox + entitlements

The app is sandboxed for Mac App Store distribution. Per project memory the sandboxing is load-bearing and is not to be removed.

Required entitlements:

• App Sandbox — the load-bearing one. All operations stay within the sandbox or go through user-mediated access (folder bookmarks, system Music.app via AppleScript with the appropriate permission prompt).
• iCloud Documents — for Locker backups.
• Apple Music — MusicKit needs the user's subscription state and library access.
• AppleScript / Apple Events — required to send events to the Music.app. First-time use prompts the user for permission.

UX conventions (project-memory locked)

Several UX details are locked decisions:

• Window size: 900×720 default.
• Minimum font: 18pt throughout (same rule that came from Tally Matrix Clock; Library Commander inherits it).
• Scan button: custom solid-blue focus-visible style with press animation, not a stock SwiftUI button.
• In-flight messaging: "One moment please…" during long operations; "Cancelling…" when the user cancels mid-flight.
• Status bar: footer status bar shows the current operation and queue state.

These aren't preferences — they're locked. Future revisions don't drift on window size, font floor, or the custom button styling.

Roadmap status

v1.0 MVP scope (the four panes, 14 task items from DeveloperNotes.swift). Per project memory: no v1.1 and no slimmed iOS companion in the v1 horizon. v2.0 is the larger architectural shift — Mac-as-server + thin iOS client — covered separately when v1.0 ships and stabilizes.

Build + deployment

• App name: NightGard Library Commander.
• Platform: macOS only.
• Frameworks: SwiftUI (UI), MusicKit (library access), AppKit (for the AppleScript / Apple Events bridges), Foundation (M3U writing).
• External services: Apple Music (requires the user's subscription for full functionality).
• Distribution: Mac App Store after submission. Sandboxed.
• Roadmap gate: Library Commander reaching the Mac App Store is a ship dependency for the book's official release.

Known gotchas

• Sandboxing is load-bearing. Per project memory, do NOT unsandbox the app. The Mac App Store requires sandboxing; any non-sandboxed direct-file-system reach belongs in NightGard Commander (the sibling), not here.
• MusicKit write API doesn't cover everything. Some library mutations require AppleScript-on-macOS. The first time the app sends an Apple event to Music.app, macOS prompts the user for permission; without that permission, those operations fail.
• iCloud Documents pickup can lag. Locker backups land in iCloud Documents; on a fresh Mac signed into the same iCloud account, the backups may take a few minutes to appear locally. The Locker UI shows the in-flight sync state.
• The DRM line is enforced in code. The Library pane's filter is part of the architecture, not a UI checkbox the user can override. Matched / subscription / purchased tracks don't show in the editable list at all; they appear only in the Stats pane.
• Sibling app coordination. File-level operations on the audio files themselves go to NightGard Commander, not here. If a user asks "why doesn't Library Commander fix this filename?" — the answer is "Library Commander is library-level; the sibling does file-level."

Sources

• Project source: github.com/fluhartyml/NightGard-Library-Commander (verified 2026-05-10).
• Canonical roadmap: NightGard Library Commander/NightGard_Library_Commander_DeveloperNotes.swift in the project repo.
• Companion music apps: Appendix M (CryoTunes Player), Appendix W (Tally Matrix Clock), Appendix L (Cryo Playlist Manager).
• Sibling project: NightGard Commander — same family, file-level focus (see project repo).
• Apple Developer Documentation: MusicKit framework reference; Music.app AppleScript dictionary.