BifrOSt-Apps

public

Latest change 090a12f6e775a0f4e5323b50c87a339503b6f3cf - Clarify template and catalog status 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: no real application is committed under `apps/`, and the production catalog has no application refs. `org.bifrost.TemplateCheck` is generated only for tests and CI; never treat it as a product or release candidate. Update this status text when the first real application is published.

## 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.

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

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.