BifrOSt-Apps

public

Latest change f67fd8437552caf5eb9371b0012e81d27c807ca3 - Add native RÚV television application 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 and CI; 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 the template directory manually. The generator performs identity validation and context-aware escaping.

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 the shared Python/GTK
generator: its Rust 2024, libcosmic, and embedded GStreamer stack serves a
native television interface. Keep the shared generator unchanged. Do not
generalize this exception into another template 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 or CI.

CI may publish an unsigned candidate bundle 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.