BifrOSt-Apps

Latest change d1154bec05736d11f362012ebaac0656e03055c0 - Migrate repository URLs to AkurAI Build by Ólafur Búi Ólafsson

1:# BifrOSt Apps Agent Guide
2:
3:## Scope
4:
5: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://akurai-build.olibuijr.com/repos/BifrOSt) on GitHub.
6:
7: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.
8:
9:Current status: `org.bifrost.Ruv` is the first real application committed under
10:`apps/`, but it has not been signed or published to the production catalog.
11:Source availability never implies catalog availability. `org.bifrost.TemplateCheck`
12:is generated only for template tests; never treat it as a product or release
13:candidate.
14:
15:## Required application contract
16:
17:- Use exactly one `org.bifrost.<PascalCaseName>` identity for the Flatpak app ID, executable, desktop file, icon, AppStream component, and gettext domain.
18:- Release catalog applications on the `stable` branch. Support `x86_64` unless the release process explicitly adds another architecture.
19:- Provide English and Icelandic names, summaries, descriptions, and user-facing translations.
20:- Pin runtimes, SDKs, downloaded sources, and generated dependency archives. Do not build from floating branches or unverified downloads.
21:- 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.
22:- Store persistent state through sandbox-standard XDG locations. Do not depend on private files below `/usr/lib/bifrost-*` or `/usr/share/bifrost`.
23:- Keep AppStream releases accurate. Update the version and release date with every candidate.
24:- Replace the template icon and demonstration status page before treating a generated app as a release candidate.
25:
26:## Creating an app
27:
28: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.
29:
30:After generation:
31:
32:1. Implement the real workflow under the generated app directory.
33:2. Preserve the generated identity across code and metadata.
34:3. Add behavior-level tests for the application's observable contracts.
35:4. Validate the desktop and AppStream files.
36:5. Build in Flatpak and exercise launch plus primary workflows from a clean user installation.
37:6. Review `finish-args` and remove permissions that the app does not use.
38:
39:RÚV is an intentional product-level exception to both templates: its Rust 2024,
40:libcosmic, and embedded GStreamer stack serves a native television interface.
41:Do not add further templates until at least two real applications require the
42:same convention.
43:
44:## Verification commands
45:
46:From the repository root on Titan:
47:
48:```bash
49:python3 -m unittest discover -s tests -v
50:```
51:
52:For each changed application, also run:
53:
54:```bash
55:desktop-file-validate apps/<app>/data/org.bifrost.<Name>.desktop
56:appstreamcli validate --no-net apps/<app>/data/org.bifrost.<Name>.metainfo.xml
57:flatpak-builder --user --install-deps-from=flathub --force-clean \
58:  --default-branch=stable build/<app> apps/<app>/org.bifrost.<Name>.yml
59:```
60:
61:For RÚV specifically, also run from the repository root:
62:
63:```bash
64:cargo fmt --check --manifest-path apps/ruv/Cargo.toml
65:cargo clippy --all-targets --locked --manifest-path apps/ruv/Cargo.toml -- -D warnings
66:cargo test --all-targets --locked --manifest-path apps/ruv/Cargo.toml
67:desktop-file-validate apps/ruv/data/org.bifrost.Ruv.desktop
68:appstreamcli validate --no-net apps/ruv/data/org.bifrost.Ruv.metainfo.xml
69:```
70:
71:For Rust/Flatpak applications, commit and review `Cargo.lock` and the generated
72:Cargo source manifest together. RÚV refreshes its immutable offline inputs from
73:the repository root with:
74:
75:```bash
76:cargo generate-lockfile --manifest-path apps/ruv/Cargo.toml
77:python3 /path/to/flatpak-builder-tools/cargo/flatpak-cargo-generator.py \
78:  apps/ruv/Cargo.lock -o apps/ruv/cargo-sources.json
79:cargo test --locked --manifest-path apps/ruv/Cargo.toml
80:```
81:
82:Flatpak manifests must use `cargo --offline --locked`; network access in the
83:installed app is not permission for dependency resolution during its build.
84:
85:A UI change is not verified by compilation alone. Launch the built Flatpak and exercise the changed path.
86:
87:## Security and release boundary
88:
89: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.
90:
91:This repository does not use GitHub Actions or any CI pipeline. A laptop is a source-control client only: commit the intended change, push it to the hosted Git remote, then fast-forward Titan with `git pull --ff-only`. Run every verification command and build on Titan before review. Unsigned candidate bundles are produced on Titan 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; that command requires a reviewed candidate manifest recording the bundle SHA-256, source revision, and application identity before it will admit a candidate (`org.bifrost.TemplateCheck` is denylisted). Changes to the namespace, branch, catalog URL, trust key, signing process, or publication contract require coordinated changes and verification in both repositories.
92:
93:## Repository hygiene
94:
95: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.
96: