Kaleido-Desktop/docs/development.md
Elijah be865fa992
All checks were successful
Validate Kaleido Desktop / validate (push) Successful in 1m21s
Document the release and push flow for future sessions
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-30 17:28:04 -07:00

3.9 KiB

Development

Setup (Windows)

  1. Node 22+, Rust stable (MSVC), Visual Studio C++ build tools, 7-Zip.
  2. npm ci
  3. .\scripts\fetch-libmpv.ps1 downloads the shinchiro mpv-dev-x86_64 build (the Windows libmpv builds linked from mpv.io) into vendor/mpv/windows.
  4. Put a .env in the repository root for the development sign-in: PLEX_SERVER_URL=... and PLEX_TOKEN=.... It is ignored by git and only read by debug builds and the Vite dev server. Never commit or print it.
  5. npm run tauri dev

The interface alone runs in a browser with npm run dev (port 1420), which is handy for layout work; playback, downloads and native dialogs need the desktop app. In development builds the stores are available as window.__kaleido for debugging.

To drive the desktop app from scripts, start it with WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9333 and attach over the Chrome DevTools Protocol.

Checks

npm run typecheck
npm test
cargo check --manifest-path src-tauri/Cargo.toml

Playback tests change real Plex progress; resume an in-progress title near its saved position, or restore it afterwards. Selecting audio or subtitle tracks is saved to Plex for that file.

Releases

Releases are built and published from this Windows machine. CI only validates; it never builds installers on push (there are no Windows/macOS runners). Versions follow SemVer; betas use a prerelease suffix (0.1.0-beta.1) and are published as pre-releases.

Checklist for version X.Y.Z (run from the repository root):

  1. Version: set X.Y.Z in package.json, src-tauri/Cargo.toml and src-tauri/tauri.conf.json, then npm install --package-lock-only to update package-lock.json.
  2. Changelog: add a ## X.Y.Z section at the top of CHANGELOG.md. It becomes the release notes and the in-app update notes.
  3. Check: npm run typecheck, npm test, cargo check --manifest-path src-tauri/Cargo.toml.
  4. Build: .\scripts\build.ps1 → src-tauri/target/release/bundle/nsis/Kaleido_X.Y.Z_x64-setup.exe and its .sig. The updater key is read from .tools/updater.key (ignored; keep it safe — replacing it breaks in-app updates for existing installs) or from TAURI_SIGNING_PRIVATE_KEY.
  5. Commit and tag: commit as Release Kaleido Desktop X.Y.Z, then git tag -a vX.Y.Z -m "Kaleido Desktop X.Y.Z" and git push origin main vX.Y.Z (SSH remote origin, already configured).
  6. Publish: node scripts/publish-release.mjs X.Y.Z (add --prerelease for betas) creates the Forgejo release with the notes from CHANGELOG.md and uploads the installer and .sig. It reads FORGEJO_TOKEN (repository read/write) from the environment or the ignored .env, and never prints it. Re-running it replaces the assets.
  7. Update feed: node scripts/update-manifest.mjs X.Y.Z https://git.elijahkuntz.com/Elijah/Kaleido-Desktop/releases/download/vX.Y.Z rewrites updates/latest.json; commit it (Publish the X.Y.Z update feed) and push. Installed copies offer the update on their next start. Publish the feed only after the release assets exist, or clients would be sent to a missing file.
  8. Verify: download the installer from the release URL and compare its SHA-256 with the local file; https://git.elijahkuntz.com/Elijah/Kaleido-Desktop/raw/branch/main/updates/latest.json should show the new version; CI on Actions should finish green.

The installer is per user (%LOCALAPPDATA%\Kaleido, no admin) and is not code-signed, so SmartScreen warns on first run. In-app updates run it in passive mode and relaunch.

For macOS and Linux, build on those systems (scripts/fetch-libmpv.sh, then npx tauri build) and merge their bundles into the same feed with KALEIDO_BUNDLES. .forgejo/workflows/release.yml validates every push and tag; .forgejo/workflows/build-installers.yml can build installers in CI once runners exist for each platform, and only runs when started by hand.