Spec — Release Packaging Formats

Applicability

Every Koder product that produces distributable artifacts (desktop, mobile, server, library). Applies to the release flow triggered by /com_rel_syn_dpl and friends.

Format Hierarchy

Priority	Format	Channel	Notes
Primary	.kpkg	Koder Hub	Universal bundle; one file, all platforms. Produced by kpkg build.
Secondary	.deb / .rpm / .AppImage / .Flatpak	Linux distros	For users who don't use Koder Hub.
Secondary	.msix / .msi	Windows	Required for Flutter desktop; WinRM → s.win.local.
Secondary	.pkg / .ipa / .apk	macOS / iOS / Android	Platform stores.
Legacy	tar.gz	Direct download	Accepted for apps not yet producing .kpkg; will be deprecated.

Rule: every Flutter desktop app must produce a .kpkg via kpkg build --from-bundle in addition to any secondary formats. The .kpkg is what khub install downloads by default; secondary formats are for external channels only.

Required Formats

When generating a release, produce packages for all applicable formats from this list:

Format	Target	Build Tool	Host Requirement
deb	Ubuntu, Debian, Mint	dpkg-deb	Linux
rpm	Fedora, Red Hat, SUSE	rpmbuild	Linux
Flatpak	Linux (sandboxed)	flatpak-builder	Linux
Snap	Linux (Canonical)	snapcraft --destructive-mode	Linux
AppImage	Linux (portable)	appimagetool	Linux
MSIX	Windows 10/11 (Flutter desktop apps)	dart run msix:create	WinRM → s.win.local ou k.win
MSI	Windows (Go CLIs / instaladores simples)	wixl (msitools)	Linux (cross-build OK)
BAT	DOS	shell	any
app	macOS Application Bundle	Xcode	macOS
pkg	macOS Installer Package	pkgbuild	macOS
ipa	iOS App Store Package	Xcode	macOS
apk	Android	Gradle / Flutter	any

Rules

1. Skip non-applicable formats — do not build an apk for a desktop-only program.
2. Skip formats the host cannot produce AND cannot install the tools for — e.g., ipa without macOS. If the tool can be installed on Linux (snapcraft, flatpak-builder, wixl, appimagetool), install it and generate the package — do not skip.
3. MSIX obrigatório para Flutter desktop — todo módulo Koder que tenha app/desktop/ (Flutter desktop) e cujo koder.toml liste "windows" em platforms, ou que possa vir a ter UI Windows (produto com usuário final, mesmo sem o diretório ainda), deve gerar .msix em toda release. Usar dart run msix:create via WinRM → s.win.local ou k.win. Ver policies/windows-builds.kmd §2 para o fluxo completo. Não pular este formato alegando "não há máquina Windows disponível" — sempre delegar para a VM.
4. Every commit gets a release — when the user asks to "commit" (via /com_rel_syn_dpl), always generate a release with all applicable packages after committing.
5. Public packages, private repos — all Koder repositories remain private. Public download of release assets is controlled by two repo-level flags:
   • public_releases=true — enables anonymous download of release assets
   • public_binaries_only=true — restricts to the Flow binary allowlist: .deb, .rpm, .apk, .aab, .appimage, .snap, .flatpak, .msi, .exe, .dmg, .pkg, .ipa, .bin, .7z, .zip, .tar.xz, .tar.zst, .tar.bz2
   • Source .tar.gz auto-generated by Flow remain private
   • Enable once per repo via:

     PATCH /api/v1/repos/{owner}/{repo}
     {"public_releases": true, "public_binaries_only": true}
     

   • After enabling, all binaries of all past and future releases are anonymous-downloadable automatically
   • Do not use PATCH .../assets/{id} with is_public:true — that field does not exist in the Flow schema and is silently ignored
   • Do not create separate *-releases repositories
6. Latest alias — after creating a release, ensure Koder Flow has the /releases/latest shortcut pointing at the newest release. The URL https://flow.koder.dev/{owner}/{repo}/releases/latest must always redirect to the latest release. Gitea/Forgejo supports this natively — do not disable.
7. Fixed-name assets for permanent downloads — when uploading assets, always upload two copies of each artifact: one with the versioned name (e.g. vivver-id-v1.0.9.apk) and one with the fixed, unversioned name (e.g. vivver-id.apk). This lets the URL https://flow.koder.dev/{owner}/{repo}/releases/download/latest/{fixed-name} work as a permanent link always pointing at the latest artifact. Fixed-name pattern: {product-name}.{ext}. When telling the user URLs, prefer the /latest/ URL with the fixed name.

Public URLs

• Recommended (readable): https://flow.koder.dev/{owner}/{repo}/releases/download/{tag}/{file} — the handler RedirectDownloadPublic is outside RepoAssignment and works anonymously.
• Alternative (top-level attachment): https://flow.koder.dev/attachments/{uuid} — also anonymous.
• Backup mirror: dl.koder.dev served from /var/www/dl.koder.dev/ on s.k.lin by koder-jet — available as a fallback if you don't want to depend on Flow.

Commit Flow Integration

The /com_rel_syn_dpl skill is the canonical way to commit + release + sync + deploy in one step. It enforces rules 1–6 automatically.