BifrOSt-Apps

public

Latest change f35619cfe0419c596645328bf0e1b682ad3a4473 - Harden RÚV for the 0.1.1 candidate by Ólafur Búi Ólafsson

# BifrOSt Apps Agent Guide

## Scope

This repository is the home for independently installable, sandboxed first-party BifrOSt applications. The sibling operating-system repository is [`../BifrOSt`](../BifrOSt) locally and [`olibuijr/BifrOSt`](https://github.com/olibuijr/BifrOSt) on GitHub.

Do not copy OS responsibilities into this repository. The OS repository owns installation media, installed-system services, the Update Assistant, the embedded application-release public key, signed catalog state, admission policy, and publication tooling. This repository owns application source, manifests, metadata, translations, tests, and unsigned release candidates.

Current status: `org.bifrost.Ruv` is the first real application committed under
`apps/`, but it has not been signed or published to the production catalog.
Source availability never implies catalog availability. `org.bifrost.TemplateCheck`
is generated only for template tests; never treat it as a product or release
candidate.

## Required application contract

- Use exactly one `org.bifrost.<PascalCaseName>` identity for the Flatpak app ID, executable, desktop file, icon, AppStream component, and gettext domain.
- Release catalog applications on the `stable` branch. Support `x86_64` unless the release process explicitly adds another architecture.
- Provide English and Icelandic names, summaries, descriptions, and user-facing translations.
- Pin runtimes, SDKs, downloaded sources, and generated dependency archives. Do not build from floating branches or unverified downloads.
- Start with no network, host filesystem, device, session-bus, or system-bus access. Add each permission only for implemented behavior and document why it is needed.
- Store persistent state through sandbox-standard XDG locations. Do not depend on private files below `/usr/lib/bifrost-*` or `/usr/share/bifrost`.
- Keep AppStream releases accurate. Update the version and release date with every candidate.
- Replace the template icon and demonstration status page before treating a generated app as a release candidate.

## Creating an app

Use `scripts/new-app.py`; do not copy a template directory manually. The generator performs identity validation and context-aware escaping. Two templates exist: `--stack gtk` (default, Python/GTK under `template/`) and `--stack dioxus` (Rust + Dioxus 0.7 desktop 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.

After generation:

1. Implement the real workflow under the generated app directory.
2. Preserve the generated identity across code and metadata.
3. Add behavior-level tests for the application's observable contracts.
4. Validate the desktop and AppStream files.
5. Build in Flatpak and exercise launch plus primary workflows from a clean user installation.
6. Review `finish-args` and remove permissions that the app does not use.

RÚV is an intentional product-level exception to both templates: its Rust 2024,
libcosmic, and embedded GStreamer stack serves a native television interface.
Do not add further templates until at least two real applications require the
same convention.

## Verification commands

From the repository root:

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

For each changed application, also run:

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

For Rust/Flatpak applications, commit and review `Cargo.lock` and the generated
Cargo source manifest together. RÚV refreshes its immutable offline inputs from
the repository root with:

```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
```

Flatpak manifests must use `cargo --offline --locked`; network access in the
installed app is not permission for dependency resolution during its build.

A UI change is not verified by compilation alone. Launch the built Flatpak and exercise the changed path.

## Security and release boundary

Never commit private keys, credentials, `.flatpak` bundles, build directories, OSTree repositories, or generated SDK state. Never add the protected BifrOSt application-release private key to local scripts.

This repository does not use GitHub Actions or any CI pipeline; run the verification commands locally before review. Unsigned candidate bundles are produced locally with a digest, source revision, exact manifest, and build log. Final admission, signing, and publication must be performed with `dispatch-app-release.py` from the BifrOSt OS repository. Changes to the namespace, branch, catalog URL, trust key, signing process, or publication contract require coordinated changes and verification in both repositories.

## Repository hygiene

Prefer one self-contained directory per application under `apps/`. Share code only after at least two real applications need the same stable behavior. Keep generated dependencies out of Git. Do not weaken validation to make a candidate pass; fix the source, manifest, metadata, or permissions.