BifrOSt-Apps

public

Latest change 9ee01c744bdd89e0d16142cb57cdff4e3d117380 - Refresh documentation after 0.2.2 and the RUV 0.1.1 candidate by Ólafur Búi Ólafsson

# BifrOSt Apps

First-party, sandboxed desktop applications for the [BifrOSt operating system](https://github.com/olibuijr/BifrOSt).

This repository owns application source, Flatpak manifests, application metadata, translations, tests, and unsigned release candidates. The operating-system repository owns the Update Assistant, embedded trust root, signed Flatpak catalog, signing policy, and publication tooling.

## Current status

The first real application, [`org.bifrost.Ruv`](apps/ruv), is committed as
source at version 0.1.1 for review and development. It is a Rust and libcosmic
television application for RÚV news, schedules, search, video on demand, and
live RÚV and RÚV 2 playback. Its responsive interface includes complete player
controls and minute-updated frames for both live channels. Source availability
is not publication: no application from this repository has yet been signed or
published to the production BifrOSt catalog — RÚV remains unsigned and
unpublished — so the Update Assistant does not offer RÚV at this revision.

`org.bifrost.TemplateCheck` is still generated temporarily by tests to
validate the shared Python/GTK template. It is not a product or release
candidate and must never be submitted to the trusted catalog.

## Create an application

Generate a complete Python, GTK 4, and Libadwaita application on the GNOME 50 Flatpak runtime:

```bash
python3 scripts/new-app.py \
org.bifrost.Notes \
"BifrOSt Notes" \
--name-is "BifrOSt-glósur" \
--summary "Write focused local notes" \
--summary-is "Skrifaðu hnitmiðaðar staðbundnar glósur" \
--description "Create, organize, and search local notes in a focused desktop application designed for BifrOSt." \
--description-is "Búðu til, skipuleggðu og leitaðu í staðbundnum glósum með hnitmiðuðu BifrOSt-forriti."
```

The default destination is `apps/notes/`. The generated application is runnable rather than an empty scaffold. Before release, replace its generic icon and status page with the application's real workflow.

Two templates exist. `--stack gtk` (the default) generates the conservative
Python, GTK 4, and Libadwaita application shown above. `--stack dioxus`
generates a Rust and Dioxus 0.7 desktop application under `template-dioxus/`,
rendered through the GNOME runtime's WebKitGTK; Dioxus apps must commit
`Cargo.lock` and `cargo-sources.json` together before their first Flatpak
build. RÚV remains a product-specific exception built with current libcosmic
because its television interface and embedded GStreamer-backed playback need a
native COSMIC rendering stack; do not copy that exception into the shared
templates.

The generator establishes these invariants:

- an `org.bifrost.<PascalCaseName>` application ID;
- matching executable, desktop, icon, AppStream, and gettext identities;
- English and Icelandic desktop and AppStream metadata;
- a `stable` Flatpak branch on the GNOME 50 runtime;
- Wayland, fallback X11, and GPU access without home-directory or network access;
- a local MIT project license and CC0 AppStream metadata license.

## Validate and build

Run the generator contract tests:

```bash
python3 -m unittest discover -s tests -v
```

For a generated application:

```bash
desktop-file-validate apps/notes/data/org.bifrost.Notes.desktop
appstreamcli validate --no-net apps/notes/data/org.bifrost.Notes.metainfo.xml
flatpak-builder --user --install-deps-from=flathub --force-clean \
--default-branch=stable build/notes apps/notes/org.bifrost.Notes.yml
```

Validate the committed RÚV application separately:

```bash
cargo test --locked --manifest-path apps/ruv/Cargo.toml
desktop-file-validate apps/ruv/data/org.bifrost.Ruv.desktop
appstreamcli validate --no-net apps/ruv/data/org.bifrost.Ruv.metainfo.xml
flatpak-builder --user --install-deps-from=flathub --force-clean \
--default-branch=stable build/ruv apps/ruv/org.bifrost.Ruv.yml
```

RÚV commits both `Cargo.lock` and the Flatpak Cargo source manifest so its
Flatpak build can run `cargo --offline --locked`. After an intentional
dependency update, regenerate and review them together:

```bash
cargo generate-lockfile --manifest-path apps/ruv/Cargo.toml
python3 /path/to/flatpak-builder-tools/cargo/flatpak-cargo-generator.py \
apps/ruv/Cargo.lock -o apps/ruv/cargo-sources.json
cargo test --locked --manifest-path apps/ruv/Cargo.toml
```

Install and launch only from a local test repository or bundle. Do not point development builds at the trusted production catalog.

## Release boundary

This repository does not use GitHub Actions or any CI pipeline; run the verification commands locally before review. An unsigned `.flatpak` candidate is produced locally together with its SHA-256 digest, source revision, exact manifest, and build log. This repository never possesses the BifrOSt application-release private key and never publishes to the trusted catalog.

After review, a release operator uses [`dispatch-app-release.py`](https://github.com/olibuijr/BifrOSt/blob/main/dispatch-app-release.py) in the operating-system repository. That command now requires a reviewed candidate manifest recording the bundle's SHA-256 digest, source revision, and application identity before admission (`org.bifrost.TemplateCheck` is denylisted). It then stages the candidate, restricts refs to `org.bifrost.*`, signs commits and repository metadata, and publishes the catalog consumed by BifrOSt Update Assistant.

See the operating-system repository's [application update documentation](https://github.com/olibuijr/BifrOSt#bifrost-application-updates) for the signing and publication command.

## What belongs here

Keep independently installable, sandboxed end-user applications here. Keep the installer, Update Assistant, maintenance utility, welcome utility, privileged helpers, OS configuration, signing keys, and catalog publication code in [`olibuijr/BifrOSt`](https://github.com/olibuijr/BifrOSt).

Start applications under `apps/`. Split one into its own repository only when it has a genuinely independent release cadence, contributor group, or access policy.

## License

Application code and the generator are released under the MIT License. Generated AppStream metadata declares CC0-1.0 so software catalogs may redistribute it.