flatpak_dart 0.3.0

flatpak_dart: ^0.3.0 copied to clipboard

FlatpakInstance gains runtime: the full ref the instance runs against, runtime/org.freedesktop.Platform/x86_64/25.08, exactly as flatpak_instance_get_runtime() reports it.

This is what identifies an instance that has no application. flatpak run on a runtime rather than an app — a --command=sh shell, flatpak-builder --run — produces an instance whose application id is genuinely empty, on the host as much as inside a sandbox, and it previously arrived anonymous. isRuntimeOnly names that case and toString() falls back to the runtime ref.

Both paths report it identically: libflatpak supplies it in-process, and the sandboxed path now requests runtime/runtime-branch from flatpak ps and reassembles the same ref. Verified against a live installation — the two agree exactly, runtime instance included.

Filter AppStream catalogs to architectures this machine can actually run. ArchPolicy selects how far to look: native (the host architecture alone), compatible (the default — the host plus what it runs natively, mirroring flatpak_get_supported_arches()), or emulated.

Emulation is detected, not configured. kernelExecutableArches() reads binfmt_misc for registrations that are enabled, carry the F flag (without which the interpreter is unreachable inside the sandbox) and whose interpreter still exists. That alone is never enough to surface an architecture: a machine with qemu-user-static registers ~31 of them while a remote may publish apps for one, so usableArches() reports only architectures that are both runnable and have a downloaded catalog. The host architecture always outranks an emulated one.

The policy applies to installed apps too. Flatpak installs an app for any architecture on request — flatpak install --arch=aarch64 succeeds on an x86_64 host — and the result is installed but unrunnable, so listApplications() now hides it. Pass allArches: true for a UI that would rather label than hide, and use canRunArch() to do the labelling.

Emulation support is cached, because a list view asks per row and a scan costs about a millisecond on a machine with qemu-user-static installed. There is no automatic invalidation: binfmt_misc does not bump its directory mtime when a registration is added, and disabling a handler in place changes neither that nor the entry count — which is exactly the case that matters. So the cache has a bounded staleness window and an explicit refreshArchSupport() for callers that know an emulator was installed, removed or toggled.

checkRunnable() answers the whole question rather than just the architecture half. Architecture support is necessary but not sufficient: a foreign-arch launch is stopped by the missing runtime for that architecture, before emulation is ever reached, and installing an app does not bring one along. It reports which of the two is missing, so a caller can tell a terminal problem from one ensureRuntime() fixes. It costs two native calls and is deliberately not folded into listApplications(), which filters on architecture alone — pure and free.

This also fixes catalog selection picking the alphabetically first architecture directory when the host's own was absent, which could serve x86_64 apps on an aarch64 machine.

Add AppStream catalog support. FlatpakClient.appStream locates a remote's downloaded catalog, refreshes it through flatpak_installation_update_appstream_sync(), and resolves full component metadata — icons, screenshots, releases, categories — via appstream_dart. installedIconPath() resolves an installed app's on-disk icon with no catalog at all, from that one app's deploy directory rather than by enumerating the installation. The refresh is a network pull of the whole catalog, so it runs on its own serial thread rather than on the calling isolate, and concurrent lookups of one catalog share a single build.

Add an xdg-desktop-portal PermissionStore client. FlatpakClient.permissionsStore reads and writes per-app permission decisions (devices, location, notifications, background), and FlatpakClient.permissionFlow drives launch-time prompts, persisting each answer. launchWithPermissions() combines the two and reports the resolved status of every permission alongside the launched instance.

Add system introspection: getVersion(), getDefaultArch(), getSupportedArches(), listSystemInstallations(), getSystemStorage(), ensureRuntime() and installExtensions(). getSystemStorage() reports unreadable df output as FlatpakRemoteException, so callers catching FlatpakException see every failure mode of the call.

Add waylandOnly to remote app listing, filtering to refs that request the wayland socket.

Delegate app lifecycle to the host when running inside a Flatpak sandbox. launch(), stop() and listRunning() route through flatpak-spawn --host there, because bwrap and the instance directory are not reachable from inside a sandbox. Requires --talk-name=org.freedesktop.Flatpak in the caller's finish-args. App ids are passed after a -- terminator so one cannot present itself as an option to a command running on the host. A delegated launch returns as soon as the app registers an instance, or as soon as the run fails — only a launch that does neither waits out the settle window.

Honour an explicit arch when no branch is given. Resolving an installed app through flatpak_installation_get_current_installed_app() silently dropped the arch and returned the host-arch ref instead.

Skip subdirectories=true extension points in installExtensions(). Their installable refs are <point>.<suffix>, enumerated from the remote, so the bare extension point resolved nowhere. versions= is now honoured alongside version=.

Batch APIs for list-shaped work: appStream.componentDetails() resolves metadata for many apps reusing one open catalog, and appStream.installedIconPaths() resolves icons from a single enumeration. The single-app forms delegate to them.

Cache AppStream catalogs under XDG_CACHE_HOME/flatpak_dart instead of a shared temp directory, keyed by a hash of the installation path. The directory is verified to be a non-symlink owned only by the current user at 0700; when it cannot be (no HOME, or the path belongs to someone else) the cache falls back to a private mkdtemp directory rather than to a predictable one another local user could pre-create. FlatpakClient.close() releases the open catalog handles.

Reap launched sandboxes from one multiplexed thread rather than one thread per running app.

New dependencies: appstream_dart and dbus. appstream_dart builds against SQLite, so sqlite-devel / libsqlite3-dev joins the prerequisites.

Require appstream_dart ^0.4.2, which moves the build hook onto hooks 2.x and code_assets 1.2.x. Its public Dart API is unchanged, so nothing here changed with it; the bump carries appstream_dart's fixes for undefined behaviour when parsing untrusted catalog attributes, and for a library search chain that could load a libappstream.so from a CWD-relative directory. The hooks and code_assets ranges here stay wide, so a Flutter SDK pinning meta 1.18.0 still resolves to the 1.x pairing — verified by building and running the Flutter example against it.