@gjsify/cli 0.43.0 → 0.44.0

package/lib/utils/flatpak-runtime.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Default GNOME-Platform runtime version. Bumped per release window.
+ * GNOME 50 = April 2026 stable; tracked in
+ * https://docs.flathub.org/docs/for-app-authors/requirements.
+ */
+export declare const DEFAULT_GNOME_RUNTIME_VERSION = "50";
+/** Default Freedesktop-Platform runtime version (LTS-ish). */
+export declare const DEFAULT_FREEDESKTOP_RUNTIME_VERSION = "24.08";
+/** Permissive GUI defaults for GTK4 + Adwaita apps. */
+export declare const DEFAULT_GUI_FINISH_ARGS: string[];
+/** Lean defaults for headless CLI tools — no display, no GPU. */
+export declare const DEFAULT_CLI_FINISH_ARGS: string[];
+/**
+ * The runtime keys, structurally — not `ConfigDataFlatpak`.
+ *
+ * Two config blocks answer this question now (`gjsify.flatpak` and
+ * `gjsify.ship.flatpak`, § the deprecation window in `utils/ship/flatpak-config.ts`),
+ * and a resolver typed to one of them would have to be duplicated for the other.
+ */
+export interface RuntimeSelection {
+    runtime?: string;
+    runtimeVersion?: string;
+}
+export interface ResolvedRuntime {
+    runtime: 'gnome' | 'freedesktop';
+    runtimeId: string;
+    sdk: string;
+    runtimeVersion: string;
+}
+/**
+ * Pick the runtime + sdk + version triple from config + CLI overrides.
+ * `--runtime` and `--runtime-version` flags win over config values.
+ */
+export declare function resolveRuntime(config: RuntimeSelection | undefined, overrides: RuntimeSelection): ResolvedRuntime;
+/**
+ * `append-path` for the build sandbox, derived from the declared SDK extensions.
+ *
+ * `/app/bin` is appended last so a build command finds the app's own binaries
+ * without knowing where they landed.
+ */
+export declare function deriveAppendPath(sdkExtensions: readonly string[]): string[];

package/lib/utils/flatpak-runtime.js

@@ -0,0 +1,54 @@
+// Which runtime a Flatpak is built against, and what the finished app may do.
+//
+// Lifted out of `commands/flatpak/` when `gjsify ship --target flatpak` became
+// the second caller (ADR 0024 § 8). Same move, same reason, as
+// `utils/app-metadata.ts`: these are facts about the APP, not about whichever
+// command happens to render them, and the second copy is the one that drifts —
+// a `DEFAULT_GNOME_RUNTIME_VERSION` bumped in one place and not the other
+// produces a `ship` Flatpak and a `flatpak init` Flatpak targeting different
+// GNOME releases from the same `package.json`.
+/**
+ * Default GNOME-Platform runtime version. Bumped per release window.
+ * GNOME 50 = April 2026 stable; tracked in
+ * https://docs.flathub.org/docs/for-app-authors/requirements.
+ */
+export const DEFAULT_GNOME_RUNTIME_VERSION = '50';
+/** Default Freedesktop-Platform runtime version (LTS-ish). */
+export const DEFAULT_FREEDESKTOP_RUNTIME_VERSION = '24.08';
+/** Permissive GUI defaults for GTK4 + Adwaita apps. */
+export const DEFAULT_GUI_FINISH_ARGS = ['--device=dri', '--share=ipc', '--socket=fallback-x11', '--socket=wayland'];
+/** Lean defaults for headless CLI tools — no display, no GPU. */
+export const DEFAULT_CLI_FINISH_ARGS = [];
+/**
+ * Pick the runtime + sdk + version triple from config + CLI overrides.
+ * `--runtime` and `--runtime-version` flags win over config values.
+ */
+export function resolveRuntime(config, overrides) {
+    const runtime = (overrides.runtime ?? config?.runtime ?? 'gnome');
+    if (runtime !== 'gnome' && runtime !== 'freedesktop') {
+        throw new Error(`gjsify flatpak: unknown runtime "${runtime}" (expected "gnome" or "freedesktop")`);
+    }
+    const runtimeVersion = overrides.runtimeVersion ??
+        config?.runtimeVersion ??
+        (runtime === 'gnome' ? DEFAULT_GNOME_RUNTIME_VERSION : DEFAULT_FREEDESKTOP_RUNTIME_VERSION);
+    if (runtime === 'gnome') {
+        return { runtime, runtimeId: 'org.gnome.Platform', sdk: 'org.gnome.Sdk', runtimeVersion };
+    }
+    return { runtime, runtimeId: 'org.freedesktop.Platform', sdk: 'org.freedesktop.Sdk', runtimeVersion };
+}
+/**
+ * `append-path` for the build sandbox, derived from the declared SDK extensions.
+ *
+ * `/app/bin` is appended last so a build command finds the app's own binaries
+ * without knowing where they landed.
+ */
+export function deriveAppendPath(sdkExtensions) {
+    const out = [];
+    for (const ext of sdkExtensions) {
+        const m = /^org\.freedesktop\.Sdk\.Extension\.([A-Za-z0-9-]+)$/.exec(ext);
+        if (m)
+            out.push(`/usr/lib/sdk/${m[1]}/bin`);
+    }
+    out.push('/app/bin');
+    return out;
+}

package/lib/utils/ship/depends.d.ts

@@ -1,4 +1,4 @@
-import type { FormatId } from './types.js';
+import type { DistroFormatId } from './types.js';
 /**
  * The GJS the bundles target (root AGENTS.md § Constraints: GJS 1.86 /
  * SpiderMonkey 140, Rolldown `firefox140`). A `--app gjs` bundle can carry
@@ -14,7 +14,7 @@ import type { FormatId } from './types.js';
  * is how a project whose bundle really does run on older GJS lowers it.
  */
 export declare const DEFAULT_GJS_FLOOR = "1.86";
-export declare function warnAboutGjsFloor(format: FormatId, floor: string): string[];
+export declare function warnAboutGjsFloor(format: DistroFormatId, floor: string): string[];
 export interface DependsInputs {
     /** GI namespaces the bundle imports, in `Ns-Version` spelling. */
     namespaces: readonly string[];
@@ -32,10 +32,7 @@ export interface DependsInputs {
     /** User-supplied additions for this format. */
     extra: readonly string[];
     /** Project-supplied table rows, filling gaps in {@link TYPELIB_PACKAGES}. */
-    typelibPackages?: Record<string, {
-        deb: string;
-        rpm: string;
-    }>;
+    typelibPackages?: Record<string, Record<DistroFormatId, string>>;
     /**
      * Paths of typelib files the payload carries itself. The namespaces they cover need no distro
      * dependency — and are derived from these filenames, never declared separately.
@@ -49,7 +46,7 @@ export interface DependsInputs {
  *
  * @throws when a namespace has no entry in the table — see the module header.
  */
-export declare function deriveDepends(format: FormatId, inputs: DependsInputs): string[];
+export declare function deriveDepends(format: DistroFormatId, inputs: DependsInputs): string[];
 /** One parsed dependency. `relation`/`version` are absent for an unversioned one. */
 export interface ParsedDepend {
     name: string;

package/lib/utils/ship/depends.js

@@ -41,7 +41,7 @@ export const DEFAULT_GJS_FLOOR = '1.86';
  * A record, not `format === 'deb' ? … : …`. The ternary reads as a two-way
  * choice and is really "deb, or ELSE rpm's package name" — measured on a third
  * format, `dmg` got `glib2`, at exit 0, in the `Depends:` of a package that has
- * no such thing. Adding a `FormatId` now fails to build here instead.
+ * no such thing. Adding a `DistroFormatId` now fails to build here instead.
  */
 const SCHEMA_COMPILER_PACKAGE = { deb: 'libglib2.0-bin', rpm: 'glib2' };
 /** Debian's `gjs` versions per suite, as measured 2026-08-15 — see {@link warnAboutGjsFloor}. */
@@ -53,10 +53,10 @@ const DEBIAN_GJS = 'trixie ships 1.82.3 and forky 1.88.1; 1.84 and 1.86 were ski
 /**
  * Which formats this Debian-suite warning is ABOUT.
  *
- * A `Record<FormatId, …>` and not `format !== 'deb'`: the negative form answers
+ * A `Record<DistroFormatId, …>` and not `format !== 'deb'`: the negative form answers
  * for every format that will ever exist, and answers "stay quiet" — so a third
  * format would inherit silence about a floor nobody has checked for its distro,
- * with no compile error. As a record, adding a `FormatId` fails to build until
+ * with no compile error. As a record, adding a `DistroFormatId` fails to build until
  * someone decides. `rpm` is false because Fedora ships a current GJS, which is a
  * measured fact about Fedora, not a default.
  */

package/lib/utils/ship/flatpak-config.d.ts

@@ -0,0 +1,66 @@
+import type { ConfigDataFlatpak, ConfigDataShip, ShipFlatpakOptions } from '../../types/config-data.js';
+import type { ShipFlatpakSettings } from './types.js';
+/**
+ * The release that stops reading `gjsify.flatpak` for the keys below.
+ *
+ * A major, not the next minor: the block is in published releases and in
+ * downstream `package.json`s that this repository does not control, and a
+ * window measured in weeks is a window nobody notices before it closes.
+ */
+export declare const LEGACY_FLATPAK_KEYS_REMOVED_IN = "1.0.0";
+/** The keys whose new home is `gjsify.ship.flatpak`, in the order the warning lists them. */
+export declare const MIGRATED_FLATPAK_KEYS: readonly ["runtime", "runtimeVersion", "sdkExtensions", "appendPath", "finishArgs", "cleanup"];
+export type MigratedFlatpakKey = (typeof MIGRATED_FLATPAK_KEYS)[number];
+/** The six keys as a reader sees them, before any default is applied. */
+export type MigratedFlatpakValues = {
+    [K in MigratedFlatpakKey]: ConfigDataFlatpak[K];
+};
+export interface PickedFlatpakBuildKeys {
+    values: MigratedFlatpakValues;
+    /** Keys that came from `gjsify.flatpak`, in {@link MIGRATED_FLATPAK_KEYS} order. */
+    fromLegacy: MigratedFlatpakKey[];
+}
+/**
+ * `gjsify.ship.flatpak.<key>` when set, else `gjsify.flatpak.<key>` — per KEY,
+ * noting which side answered.
+ *
+ * Per-key and not per-block: a project migrating one key at a time must not
+ * lose the five it has not moved yet. That is also what makes the warning
+ * actionable — it names the keys still coming from the old block, so the reader
+ * knows what to edit rather than being told a block is deprecated.
+ *
+ * A LOOP over {@link MIGRATED_FLATPAK_KEYS}, not six hand-written picks. Written
+ * out, the list was the one unbound copy of this vocabulary: a key added to it
+ * with no `pick` call behind it compiled fine, went missing from the window, and
+ * the only test that mentioned the constant compared it to a literal copy of
+ * itself. Reading the keys off the constant is what makes "this list IS the
+ * window" true rather than asserted.
+ *
+ * NO default is applied here. The defaults differ per reader — `ship` derives
+ * `finishArgs` from `kind`, `flatpak init` also merges `--sdk-extension` flags —
+ * and a default applied here would be a third answer neither of them chose.
+ */
+export declare function pickFlatpakBuildKeys(preferred: ShipFlatpakOptions | undefined, legacy: ConfigDataFlatpak): PickedFlatpakBuildKeys;
+/** The branch a `ship` Flatpak is exported under when the project names none. */
+export declare const DEFAULT_SHIP_FLATPAK_BRANCH = "stable";
+export interface ShipFlatpakInput {
+    ship: ConfigDataShip;
+    flatpak: ConfigDataFlatpak;
+    /** Decides the finish-args default: a GUI app needs a display, a CLI does not. */
+    kind: 'app' | 'cli';
+}
+export interface ResolvedShipFlatpak {
+    settings: ShipFlatpakSettings;
+    warnings: string[];
+}
+/**
+ * Resolve the Flatpak half of `gjsify.ship`, reading the legacy block where the
+ * new one is silent, and applying `ship`'s own defaults.
+ *
+ * The per-key fallback itself is {@link pickFlatpakBuildKeys}, shared with
+ * `gjsify flatpak init`/`ci`; what is `ship`-specific and stays here is the
+ * defaulting — `branch`, the `kind`-dependent finish-args, the derived
+ * `appendPath` — plus the warning, which only `ship` prints because only `ship`
+ * has somewhere else to point at.
+ */
+export declare function resolveShipFlatpakSettings(input: ShipFlatpakInput): ResolvedShipFlatpak;

package/lib/utils/ship/flatpak-config.js

@@ -0,0 +1,132 @@
+// The deprecation window on the `gjsify.flatpak` build keys (ADR 0024 § 8).
+//
+// § 8 names the cost of the migration and does not let it be skipped:
+// "`gjsify.flatpak` is a published config contract, so the keys move with a
+// deprecation window in which both spellings resolve and the old one warns."
+// This file is that window.
+//
+// WHAT MOVED and what did not — the table is `docs/ship-formats.md`, and the
+// short form is: the six BUILD keys moved and warn from the old spelling; the
+// `AppMetadata` half is a designed ALIAS and is NOT deprecated (both blocks
+// describe the same app, and warning on it would print for every project that
+// has a `gjsify.flatpak` block at all); and the TOOLCHAIN keys are untouched
+// because `gjsify flatpak <sub>` has not moved, so deprecating them would warn
+// on commands with nowhere else to read from.
+//
+// A WINDOW HAS TWO SIDES, and the first cut only built one. The six build keys
+// are read by `gjsify flatpak init` and `flatpak ci` as well, and those
+// commands have NOT moved — so a project that did what this file's warning told
+// it to do, and moved them, silently lost them there: `flatpak init` fell back
+// to its own defaults and wrote a manifest against a different
+// `org.gnome.Platform` version with different finish-args, committed, at exit 0.
+// That is why {@link pickFlatpakBuildKeys} is exported and BOTH command groups
+// go through it. "Both spellings resolve" is now true of every reader of these
+// keys, which is what makes the advice safe to follow.
+//
+// WHY A NAMED VERSION, IN ONE PLACE. The precedent is
+// `utils/normalize-bundler-options.ts`, the `esbuild` → `bundler` shim, and it
+// also carries the precedent's DEFECT: its warning text names 0.5.0, the tree is
+// far past it, and its header now has to say "removing the shim means fixing
+// that string too". So the version here is a constant the message reads, and the
+// spec asserts the message names it.
+import { DEFAULT_CLI_FINISH_ARGS, DEFAULT_GUI_FINISH_ARGS, deriveAppendPath, resolveRuntime, } from '../flatpak-runtime.js';
+/**
+ * The release that stops reading `gjsify.flatpak` for the keys below.
+ *
+ * A major, not the next minor: the block is in published releases and in
+ * downstream `package.json`s that this repository does not control, and a
+ * window measured in weeks is a window nobody notices before it closes.
+ */
+export const LEGACY_FLATPAK_KEYS_REMOVED_IN = '1.0.0';
+/** The keys whose new home is `gjsify.ship.flatpak`, in the order the warning lists them. */
+export const MIGRATED_FLATPAK_KEYS = [
+    'runtime',
+    'runtimeVersion',
+    'sdkExtensions',
+    'appendPath',
+    'finishArgs',
+    'cleanup',
+];
+/**
+ * `gjsify.ship.flatpak.<key>` when set, else `gjsify.flatpak.<key>` — per KEY,
+ * noting which side answered.
+ *
+ * Per-key and not per-block: a project migrating one key at a time must not
+ * lose the five it has not moved yet. That is also what makes the warning
+ * actionable — it names the keys still coming from the old block, so the reader
+ * knows what to edit rather than being told a block is deprecated.
+ *
+ * A LOOP over {@link MIGRATED_FLATPAK_KEYS}, not six hand-written picks. Written
+ * out, the list was the one unbound copy of this vocabulary: a key added to it
+ * with no `pick` call behind it compiled fine, went missing from the window, and
+ * the only test that mentioned the constant compared it to a literal copy of
+ * itself. Reading the keys off the constant is what makes "this list IS the
+ * window" true rather than asserted.
+ *
+ * NO default is applied here. The defaults differ per reader — `ship` derives
+ * `finishArgs` from `kind`, `flatpak init` also merges `--sdk-extension` flags —
+ * and a default applied here would be a third answer neither of them chose.
+ */
+export function pickFlatpakBuildKeys(preferred, legacy) {
+    const ship = preferred ?? {};
+    // Assembled through an index signature because the value type varies per
+    // key; the cast is on the finished object, where every key is present.
+    const values = {};
+    const fromLegacy = [];
+    for (const key of MIGRATED_FLATPAK_KEYS) {
+        const own = ship[key];
+        if (own !== undefined) {
+            values[key] = own;
+            continue;
+        }
+        const inherited = legacy[key];
+        if (inherited !== undefined)
+            fromLegacy.push(key);
+        values[key] = inherited;
+    }
+    return { values: values, fromLegacy };
+}
+/** The branch a `ship` Flatpak is exported under when the project names none. */
+export const DEFAULT_SHIP_FLATPAK_BRANCH = 'stable';
+/**
+ * Resolve the Flatpak half of `gjsify.ship`, reading the legacy block where the
+ * new one is silent, and applying `ship`'s own defaults.
+ *
+ * The per-key fallback itself is {@link pickFlatpakBuildKeys}, shared with
+ * `gjsify flatpak init`/`ci`; what is `ship`-specific and stays here is the
+ * defaulting — `branch`, the `kind`-dependent finish-args, the derived
+ * `appendPath` — plus the warning, which only `ship` prints because only `ship`
+ * has somewhere else to point at.
+ */
+export function resolveShipFlatpakSettings(input) {
+    const shipFlatpak = input.ship.flatpak ?? {};
+    const { values, fromLegacy } = pickFlatpakBuildKeys(shipFlatpak, input.flatpak);
+    const resolved = resolveRuntime(values, {});
+    const extensions = values.sdkExtensions ?? [];
+    const { appendPath, finishArgs, cleanup } = values;
+    const settings = {
+        runtime: resolved.runtimeId,
+        runtimeVersion: resolved.runtimeVersion,
+        sdk: resolved.sdk,
+        branch: shipFlatpak.branch ?? DEFAULT_SHIP_FLATPAK_BRANCH,
+        sdkExtensions: [...extensions],
+        // Derived from the extensions when nothing was declared, and only then:
+        // an extension whose `/usr/lib/sdk/<x>/bin` is not on PATH inside the
+        // sandbox is an extension the build cannot use, which looks like the
+        // extension not being installed.
+        appendPath: appendPath ?? (extensions.length > 0 ? deriveAppendPath(extensions) : []),
+        finishArgs: finishArgs ?? (input.kind === 'cli' ? DEFAULT_CLI_FINISH_ARGS : DEFAULT_GUI_FINISH_ARGS),
+        cleanup: cleanup ?? [],
+    };
+    return { settings, warnings: fromLegacy.length === 0 ? [] : [deprecationWarning(fromLegacy)] };
+}
+/** One line, naming every key still read from the old block and where each goes. */
+function deprecationWarning(keys) {
+    const list = keys.map((key) => `gjsify.flatpak.${key}`).join(', ');
+    const moved = keys.map((key) => `gjsify.ship.flatpak.${key}`).join(', ');
+    return (`DEPRECATION: ${list} ${keys.length > 1 ? 'are' : 'is'} read by \`gjsify ship\` for compatibility and ` +
+        `will be removed in ${LEGACY_FLATPAK_KEYS_REMOVED_IN}. Move ${keys.length > 1 ? 'them' : 'it'} to ` +
+        `${moved} — both spellings resolve until then, and \`gjsify.ship.flatpak\` wins where both are set. ` +
+        'The app METADATA in `gjsify.flatpak` (name, summary, developer, categories, licence) is NOT ' +
+        'deprecated: both blocks describe the same application and either may carry it (ADR 0024 § 8).');
+}

package/lib/utils/ship/flatpak.d.ts

@@ -0,0 +1,45 @@
+import type { PackSettings } from './types.js';
+export interface FlatpakManifestInput {
+    settings: PackSettings;
+    /** Absolute path of the staged payload — the tree `readStage` validated. */
+    stageDir: string;
+    /** Absolute path of this format's rendered overlay (the licence file). */
+    overlayDir: string;
+    /** The stage's own closure file, which is not payload and must not be copied into `/app`. */
+    stageManifestFile: string;
+}
+/**
+ * The generated Flatpak manifest, as a plain object.
+ *
+ * Pure, so every field is unit-testable without flatpak tooling — and the
+ * suite that needs that is the one running in CI, where there is none.
+ *
+ * The app id is what makes this legal Flatpak: every file flatpak EXPORTS out
+ * of `/app/share` has to be named after it, and `planStage` already enforces
+ * exactly that for its own reasons — the desktop entry, the metainfo, the icon,
+ * the GSettings schema and the shared-mime-info document are all
+ * `<appId>[.…].<ext>`, because `share/glib-2.0/schemas/` and
+ * `share/mime/packages/` are directories shared between packages. Two
+ * independent constraints, one naming rule.
+ */
+export declare function renderShipFlatpakManifest(input: FlatpakManifestInput): Record<string, unknown>;
+export interface FlatpakPackInput extends FlatpakManifestInput {
+    /** Working root for the manifest, the build dir, the repo and the builder's state. */
+    workDir: string;
+    /** Absolute path the finished `.flatpak` is written to. */
+    target: string;
+    /** Flatpak's spelling of the architecture, e.g. `x86_64`. */
+    archLabel: string;
+    verbose: boolean;
+}
+/**
+ * Build the app and export a single-file bundle at `input.target`.
+ *
+ * The only packer in this tree that execs anything, and the descriptor says so
+ * (`FORMATS.flatpak.host.requiredTools`). ADR 0024 § A3 is explicit that this
+ * costs the independent oracle the hand-written deb/rpm writers bought: what
+ * pays it back here is that a `.flatpak` is an OSTree static delta, so
+ * `flatpak build-import-bundle` + `ostree ls -R` read the artifact back with
+ * code this tree did not write.
+ */
+export declare function buildFlatpakBundle(input: FlatpakPackInput): Promise<void>;

package/lib/utils/ship/flatpak.js

@@ -0,0 +1,148 @@
+// The Flatpak packer — ADR 0024 § 8, stage 6.
+//
+// This is a MOVE, not a second implementation. `gjsify flatpak` has emitted
+// Flatpak manifests since long before `ship` existed; what it emitted was a
+// `buildsystem: meson` module, which made every app carry meson glue whose only
+// job was to call `gjsify build` and copy the result into a prefix — 158 lines
+// of it in Learn6502, 66 of them `GI_TYPELIB_PATH`/`LD_LIBRARY_PATH` plumbing.
+// `ship` already produces that prefix. So the module becomes:
+//
+//     buildsystem: simple
+//     build-commands: mkdir -p /app; cp -a stage/. /app/; cp -a overlay/. /app/
+//
+// and meson leaves the sandbox. Nothing else about the payload changes — the
+// launcher derives its own prefix at runtime (§ 3), which is exactly why one
+// staged tree can be `/usr` in a `.deb` and `/app` here.
+//
+// FOUR THINGS ABOUT flatpak-builder 1.4.10 WERE MEASURED before this file was
+// written, because each had a plausible wrong answer and flatpak-builder reports
+// none of them: an absolute `dir` source `path` works, `skip` works and is what
+// keeps the stage's own sidecar out of `/app`, `cp -a` preserves the mode, and
+// `--show-manifest` is NOT a validator (it accepted an unknown source property
+// and `buildsystem: "nonsense"` at exit 0, so it must never be used as a gate).
+// The numbers, the commands and the oracle that replaces `--show-manifest`:
+// `docs/ship-formats.md`.
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describeExit, spawnToCompletion } from '../spawn.js';
+/**
+ * The generated Flatpak manifest, as a plain object.
+ *
+ * Pure, so every field is unit-testable without flatpak tooling — and the
+ * suite that needs that is the one running in CI, where there is none.
+ *
+ * The app id is what makes this legal Flatpak: every file flatpak EXPORTS out
+ * of `/app/share` has to be named after it, and `planStage` already enforces
+ * exactly that for its own reasons — the desktop entry, the metainfo, the icon,
+ * the GSettings schema and the shared-mime-info document are all
+ * `<appId>[.…].<ext>`, because `share/glib-2.0/schemas/` and
+ * `share/mime/packages/` are directories shared between packages. Two
+ * independent constraints, one naming rule.
+ */
+export function renderShipFlatpakManifest(input) {
+    const { settings, stageDir, overlayDir } = input;
+    const flatpak = settings.flatpak;
+    const manifest = {
+        id: settings.appId,
+        runtime: flatpak.runtime,
+        'runtime-version': flatpak.runtimeVersion,
+        sdk: flatpak.sdk,
+        branch: flatpak.branch,
+        // `bin/<binaryName>`, which is the one executable the stage plans. NOT
+        // the app id, which is what `gjsify flatpak init` defaults to: under
+        // `ship` the launcher's name is decided by `gjsify.ship.binaryName`, and
+        // a `command` naming a file that is not in `/app/bin` produces an app
+        // that installs and cannot be launched.
+        command: settings.binaryName,
+        'finish-args': flatpak.finishArgs,
+    };
+    if (flatpak.sdkExtensions.length > 0)
+        manifest['sdk-extensions'] = flatpak.sdkExtensions;
+    if (flatpak.appendPath.length > 0) {
+        manifest['build-options'] = { 'append-path': flatpak.appendPath.join(':') };
+    }
+    if (flatpak.cleanup.length > 0)
+        manifest.cleanup = flatpak.cleanup;
+    manifest.modules = [
+        {
+            name: settings.binaryName,
+            buildsystem: 'simple',
+            // `mkdir -p /app` first: flatpak-builder creates the app directory,
+            // but a module whose only command is a `cp` into a path that does
+            // not exist yet is one refactor away from failing, and the mkdir is
+            // free. `stage/.` and not `stage` — `cp -a stage /app/` would
+            // create `/app/stage`, which installs cleanly and puts the whole
+            // payload one directory too deep.
+            'build-commands': ['mkdir -p /app', 'cp -a stage/. /app/', 'cp -a overlay/. /app/'],
+            sources: [
+                { type: 'dir', path: stageDir, dest: 'stage', skip: [input.stageManifestFile] },
+                { type: 'dir', path: overlayDir, dest: 'overlay' },
+            ],
+        },
+    ];
+    return manifest;
+}
+/**
+ * Build the app and export a single-file bundle at `input.target`.
+ *
+ * The only packer in this tree that execs anything, and the descriptor says so
+ * (`FORMATS.flatpak.host.requiredTools`). ADR 0024 § A3 is explicit that this
+ * costs the independent oracle the hand-written deb/rpm writers bought: what
+ * pays it back here is that a `.flatpak` is an OSTree static delta, so
+ * `flatpak build-import-bundle` + `ostree ls -R` read the artifact back with
+ * code this tree did not write.
+ */
+export async function buildFlatpakBundle(input) {
+    const { settings, workDir, archLabel } = input;
+    const manifestPath = join(workDir, `${settings.appId}.json`);
+    const buildDir = join(workDir, 'build');
+    const repoDir = join(workDir, 'repo');
+    // Kept between runs: it is flatpak-builder's own ostree cache, and dropping
+    // it turns every re-pack into a full rebuild of every module.
+    const stateDir = join(workDir, 'state');
+    mkdirSync(workDir, { recursive: true });
+    // The repo is wiped, the state dir is not. A repo that survives holds the
+    // PREVIOUS commit on the same ref, and `build-bundle` would happily export
+    // it if this run's export failed for any reason that did not fail the
+    // build — a stale artifact wearing the new version's filename.
+    rmSync(repoDir, { recursive: true, force: true, maxRetries: 5 });
+    writeFileSync(manifestPath, `${JSON.stringify(renderShipFlatpakManifest(input), null, 2)}\n`);
+    await run('flatpak-builder', [
+        '--force-clean',
+        // Needed wherever FUSE is unavailable — containers, most CI runners.
+        // It only disables a read-only-bind optimisation, and a build that
+        // cannot start is worse than one that copies a few more bytes.
+        '--disable-rofiles-fuse',
+        '--delete-build-dirs',
+        `--state-dir=${stateDir}`,
+        `--arch=${archLabel}`,
+        `--repo=${repoDir}`,
+        buildDir,
+        manifestPath,
+    ], input, 'flatpak-builder not found. Install it (Fedora: `sudo dnf install flatpak-builder`).');
+    // The branch is passed explicitly even though the manifest declares it: the
+    // two have to name the same ref, and `build-bundle`'s default is `master`
+    // while a manifest that sets `branch` exports somewhere else. Leaving it
+    // implicit is how this exports nothing and says "ref not found".
+    await run('flatpak', ['build-bundle', `--arch=${archLabel}`, repoDir, input.target, settings.appId, settings.flatpak.branch], input, 'flatpak not found. Install it via your distro: see https://flathub.org/setup.');
+}
+async function run(cmd, args, input, notFoundHint) {
+    if (input.verbose)
+        console.log(`[gjsify ship] ${cmd} ${args.join(' ')}`);
+    // `completion: 'return'` because `ship` packs the remaining formats and
+    // prints the artifact list afterwards, so it cannot end in `process.exit()`
+    // the way `gjsify flatpak build` does. Under GJS that selects the blocking
+    // path, which captures the child's output and re-emits it at the end
+    // instead of streaming it — the documented cost of a spawn a caller has to
+    // return from (see utils/spawn.ts), and the reason `--verbose` prints the
+    // invocation before the silence starts.
+    const result = await spawnToCompletion(cmd, args, {
+        completion: 'return',
+        cwd: input.workDir,
+        stdio: 'inherit',
+        notFound: () => new Error(`gjsify ship: ${notFoundHint}`),
+    });
+    if (result.code !== 0) {
+        throw new Error(`gjsify ship: ${cmd} failed${describeExit(result)}.`);
+    }
+}

package/lib/utils/ship/formats.d.ts

@@ -1,5 +1,40 @@
 import type { FormatDescriptor, FormatId } from './types.js';
 export declare const FORMATS: Record<FormatId, FormatDescriptor>;
 export declare const FORMAT_IDS: FormatId[];
+/**
+ * What `gjsify ship` builds when nothing said otherwise — every format that
+ * needs no tool and no particular host.
+ *
+ * A SECOND derivation from the same table, and it has to be one: `FORMAT_IDS`
+ * used to be both "every format that exists" and "every format to build by
+ * default", which was the same list only while every format was `finishOn:
+ * 'any'`. Adding Flatpak to `FORMAT_IDS` alone would have made a bare
+ * `gjsify ship` demand `flatpak-builder` of every project that ever packaged a
+ * `.deb` — and on a host without it, of every `release-cut.yml` run, which
+ * packs `@gjsify/cli` itself on a bare ubuntu runner. A host-bound format is
+ * opt-in through `--target` or `gjsify.ship.targets`; `--help` still lists all
+ * of them.
+ */
+export declare const DEFAULT_FORMAT_IDS: FormatId[];
+/**
+ * Refuse a format this host cannot finish, BEFORE anything is built or written.
+ *
+ * `host` is injected so both branches are unit-testable from any machine — the
+ * same reason `resolvePrebuildDirName` and `checkTypeSkew`'s readers are pure.
+ * The message names the two-phase split rather than just saying no: the answer
+ * to "I am on macOS and want a Flatpak" is `--stage` here and `--from-stage` on
+ * a Linux runner, and a refusal that does not say so reads as "unsupported".
+ */
+export declare function assertHostCanFinish(format: FormatDescriptor, host?: string): void;
+/**
+ * Refuse a format whose tools are not installed, with the tool named.
+ *
+ * Separate from {@link assertHostCanFinish} because the two failures have
+ * different fixes — one needs a different machine, the other needs a package —
+ * and separate from the packer's own `notFound` handler because it fires BEFORE
+ * a build: `gjsify ship` runs the project's `build` script first, and finding
+ * out afterwards that `flatpak-builder` is absent costs the whole build.
+ */
+export declare function assertToolsInstalled(format: FormatDescriptor, present?: (cmd: string) => boolean): void;
 /** Parse `--target deb,rpm` into a sorted, deduplicated descriptor list. */
 export declare function resolveFormats(raw: readonly string[]): FormatDescriptor[];