PixelBullet Launcher — Documentation

This site contains guides and the generated API reference.

The content below mirrors the repository README.

PixelBullet Launcher

Pipeline Status Coverage Report

Avalonia (.NET 8) desktop launcher and CLI that share a common Core. The launcher fetches artifacts from a URL or JSON manifest, verifies them, installs to a predictable directory, and can optionally run the app immediately.

Features

  • Cross-platform UI (Avalonia 11) and CLI (Spectre.Console)
  • Clear Core abstractions:
    • IManifestProvider – fetches LauncherManifest
    • IInstaller – downloads & installs artifacts (ZIPs supported)
    • IRunner – launches the installed app
  • Install locations: %LOCALAPPDATA%/PixelBullet/Apps/{id}/{channel} (or equivalent on Linux/macOS)
  • SHA-256 verification for artifacts (if provided in manifest)
  • Post-install run (Desktop: Run button; CLI: --run)
  • Stubs for local dev (PB_USE_STUBS=1)

Project Structure

  • src/PixelBullet.Launcher.Core – Domain services and models (no UI deps)
  • src/PixelBullet.Launcher.Desktop – Avalonia 11 desktop app (MVVM via CommunityToolkit.Mvvm)
  • src/PixelBullet.Launcher.Cli – Spectre.Console-based CLI (pbctl)
  • tests/PixelBullet.Launcher.Core.Tests – Unit tests for Core

Supported RIDs (auto-detected): win-x64, win-arm64, linux-x64, linux-arm64, osx-x64, osx-arm64.

Quick Start

Desktop:

dotnet run --project src/PixelBullet.Launcher.Desktop

CLI:

# Install from a .zip (auto-wraps into a manifest for current platform)
dotnet run --project src/PixelBullet.Launcher.Cli -- \
  --manifest https://example.com/artifact.zip \
  --channel stable

# ...and run immediately after install
dotnet run --project src/PixelBullet.Launcher.Cli -- \
  --manifest https://example.com/artifact.zip \
  --channel stable \
  --run

Tip: If you pass a .json URL, the CLI expects a LauncherManifest. Otherwise it treats the URL as a direct artifact for the current platform.

Stubs (no network/downloads):

PB_USE_STUBS=1 dotnet run --project src/PixelBullet.Launcher.Cli
PB_USE_STUBS=1 dotnet run --project src/PixelBullet.Launcher.Desktop

Manifest (JSON)

Minimal example describing a single artifact per platform. If Sha256 is present it is verified. Exe is the path inside the extracted ZIP that should be launched. Optional Args are passed on run.

{
  "Id": "com.pixelbullet.app",
  "Channel": "stable",
  "Artifacts": [
    {
      "Platform": "win-x64",
      "Kind": "zip",
      "Uri": "https://example.com/app_win.zip",
      "Sha256": "<hex or sha256-...>",
      "Size": 12345678,
      "Exe": "App/App.exe",
      "Args": ["--example", "value"]
    }
  ],
  "Version": "1.2.3",
  "ReleaseNotesUrl": "https://example.com/release-notes"
}

Install root: %LOCALAPPDATA%/PixelBullet/Apps/<Id>/<Channel> on Windows, similarly under LocalApplicationData on Linux/macOS.

CLI Usage

pbctl install [--manifest <URI>] [--channel <stable|beta|nightly>] [--run] [--open-dir]
  • --manifest – absolute URL to a .json manifest or a direct artifact (e.g. .zip)
  • --channel – one of stable|beta|nightly (default: stable)
  • --run – launch after a successful install
  • --open-dir – open install directory after install

Return code: 0 success, 1 error. Press Ctrl+C to cancel an in-progress install.

Development

Build:

dotnet build -c Release

Test:

dotnet test -c Release

Publish example (self-contained single file):

dotnet publish src/PixelBullet.Launcher.Desktop -c Release -r linux-x64 \
  -p:PublishSingleFile=true --self-contained true

Notes:

  • Executable publish settings are centralized in Directory.Build.props.
  • Line endings are normalized via .gitattributes (LF for code/docs; CRLF for .bat).

License

See LICENSE.

API Reference

See API Reference in the left navigation.