@gjsify/cli 0.43.0 → 0.44.0

package/lib/utils/ship/formats.js

@@ -1,7 +1,13 @@
-// The per-format table. Everything that differs between `.deb` and `.rpm`
-// outside the archive container itself lives here as DATA, so a new format is
-// a row rather than an edit across the stager, the overlay builder and the
-// artifact namer.
+// The per-format table. Everything that differs between the formats outside the
+// archive container itself lives here as DATA, so a new format is a row rather
+// than an edit across the stager, the overlay builder and the artifact namer.
+//
+// Flatpak is the row that proves the claim: ADR 0024 § 2 predicted "the whole
+// difference between a Flatpak and an `.rpm` is a four-line prefix map", and
+// this file is where that turned out to be one `prefix: '/app'`, one arch table
+// and one filename. What it also proved is what the design did NOT predict —
+// a format can be host-bound (§ A3), so `host` is a descriptor field now.
+import { isOnPath } from '../check-system-deps.js';
 // `process.arch` → the format's architecture name. Taken from dpkg's own
 // `data/cputable` and rpm's arch table. `arm` cannot be told apart from
 // `armel` by a running process, and Debian's hard-float port is what anything
@@ -32,16 +38,49 @@ function lookupArch(table, arch, label) {
     }
     return mapped;
 }
+// Flatpak's own vocabulary, which is ostree's: `flatpak --supported-arches` on
+// x86_64 answers `x86_64` then `i386`, and a ref is `app/<id>/<arch>/<branch>`.
+// Deliberately short — a name this table does not know is refused rather than
+// guessed, because the arch is not a label here, it is part of the ref the
+// bundle is exported under and installed from.
+const FLATPAK_ARCH = {
+    x64: 'x86_64',
+    arm64: 'aarch64',
+    ia32: 'i386',
+    arm: 'arm',
+};
 function debArch(arch, archIndependent) {
     return archIndependent ? 'all' : lookupArch(DEBIAN_ARCH, arch, 'Debian');
 }
 function rpmArch(arch, archIndependent) {
     return archIndependent ? 'noarch' : lookupArch(RPM_ARCH, arch, 'RPM');
 }
+/**
+ * Flatpak has no `noarch`, so `archIndependent` is ignored — and that is a
+ * measured difference, not an oversight.
+ *
+ * `all`/`noarch` exist because apt and dnf REFUSE a package whose architecture
+ * is not the machine's. Flatpak asks the opposite question: every ref names an
+ * arch, `flatpak install` resolves the one matching the host, and an app with no
+ * arch is not installable at all. So a payload of pure JavaScript still ships as
+ * `app/<id>/x86_64/stable` — which is also what Flathub does for every
+ * interpreted app it hosts.
+ */
+function flatpakArch(arch, _archIndependent) {
+    return lookupArch(FLATPAK_ARCH, arch, 'Flatpak');
+}
+/** `.deb` and `.rpm` are written by this tree, so they exec nothing and read back with GNU tools. */
+const WRITTEN_HERE = (readWith) => ({
+    finishOn: 'any',
+    requiredTools: [],
+    oracle: { readWith, readOn: ['linux'], selfReading: false },
+});
 export const FORMATS = {
     deb: {
         id: 'deb',
         prefix: '/usr',
+        host: WRITTEN_HERE(['ar', 'tar', 'dpkg-deb', 'lintian']),
+        depends: 'deb',
         // Debian policy § 12.5: every package ships its copyright in
         // /usr/share/doc/<package>/copyright, and lintian errors without it.
         licenseDest: (binaryName) => `share/doc/${binaryName}/copyright`,
@@ -52,21 +91,121 @@ export const FORMATS = {
     rpm: {
         id: 'rpm',
         prefix: '/usr',
+        host: WRITTEN_HERE(['rpm', 'rpm2cpio', 'cpio']),
+        depends: 'rpm',
         licenseDest: (binaryName) => `share/licenses/${binaryName}/LICENSE`,
         licenseKind: 'plain',
         archName: rpmArch,
         fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.${archLabel}.rpm`,
     },
+    flatpak: {
+        id: 'flatpak',
+        // The one-line difference ADR 0024 § 2 promised. Nothing in the payload
+        // changes: the launcher derives its prefix at runtime (§ 3), so the same
+        // staged `bin/<name>` works under /usr and under /app.
+        prefix: '/app',
+        host: {
+            // A single-file bundle is an OSTree static delta, and the only writer
+            // of one is `flatpak build-bundle`. Unlike the `.dmg` (§ A6) that is
+            // not an OS restriction: flatpak runs on Linux, so the format is
+            // Linux-bound the way the app itself is.
+            finishOn: ['linux'],
+            requiredTools: ['flatpak-builder', 'flatpak'],
+            installHint: 'Fedora: `sudo dnf install flatpak flatpak-builder`, Debian/Ubuntu: ' +
+                '`sudo apt install flatpak flatpak-builder`',
+            oracle: {
+                // `flatpak build-import-bundle` into a FRESH repo, then
+                // `ostree ls -R`: ostree parses the delta this tree never wrote,
+                // and prints a path + mode + size per file. Measured on this
+                // workstation — that listing is what the e2e suite compares
+                // against the staged payload.
+                readWith: ['flatpak', 'ostree'],
+                readOn: ['linux'],
+                selfReading: false,
+            },
+        },
+        // A Flatpak's one dependency is its runtime, named in the manifest. See
+        // `DistroFormatId`: there is no `Depends:` field here to under-declare,
+        // which also means the unmapped-namespace refusal ADR 0024 § 6 built for
+        // deb and rpm has nothing to say about this format.
+        depends: null,
+        // No policy demands a location, so this follows rpm's — one fewer shape
+        // for a reader to learn, and `/app/share/licenses/<name>/LICENSE` is
+        // where the equivalent file sits in the `.rpm` built from the same stage.
+        licenseDest: (binaryName) => `share/licenses/${binaryName}/LICENSE`,
+        licenseKind: 'plain',
+        archName: flatpakArch,
+        // Named after the APP ID, not the binary: the id is the ref the file
+        // installs as, and it is what `flatpak install ./file.flatpak` prints.
+        fileName: (s, archLabel) => `${s.appId}-${s.version}-${s.release}.${archLabel}.flatpak`,
+    },
 };
 // DERIVED, never a second list. `FORMATS` is `Record<FormatId, …>`, so the
 // compiler already refuses a `FormatId` with no descriptor — reading the keys
 // back inherits that guarantee for free. Written out by hand this was the one
 // unbound copy of the vocabulary: adding a format to `FormatId` and `FORMATS`
 // compiled fine and left this list short, which would have made the new format
-// absent from the default targets (`ship.ts` uses it as the `??` fallback),
-// missing from `--help`, and REFUSED by `readStage` as an unknown id.
+// missing from `--help` and REFUSED by `readStage` as an unknown id.
 // Insertion order is stable for string keys, and `resolveFormats` sorts anyway.
 export const FORMAT_IDS = Object.keys(FORMATS);
+/**
+ * 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 const DEFAULT_FORMAT_IDS = FORMAT_IDS.filter((id) => FORMATS[id].host.finishOn === 'any');
+/**
+ * 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 function assertHostCanFinish(format, host = process.platform) {
+    const { finishOn } = format.host;
+    if (finishOn === 'any' || finishOn.includes(host))
+        return;
+    throw new Error(`gjsify ship: a ${format.id} artifact is packed on ${finishOn.join(' or ')} and ` +
+        `this host is ${host} (ADR 0024 § A1: a container is produced where its format's tool lives). ` +
+        'Assembly is not host-bound, so the way across is the two-phase split: run ' +
+        '`gjsify ship --stage` here, move `ship/stage/` to a ' +
+        `${finishOn.join('/')} runner, and finish with ` +
+        `\`gjsify ship --from-stage <dir> --target ${format.id}\`.`);
+}
+/**
+ * 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 function assertToolsInstalled(format, present = isOnPath) {
+    const missing = format.host.requiredTools.filter((tool) => !present(tool));
+    if (missing.length === 0)
+        return;
+    // The install instruction is the DESCRIPTOR's, not this function's: hardcoded
+    // here it was `dnf install flatpak flatpak-builder` for every format that
+    // will ever need a tool, which is the branch this table exists to avoid.
+    const hint = format.host.installHint;
+    throw new Error(`gjsify ship: packing a ${format.id} needs ${format.host.requiredTools.join(' and ')}, and ` +
+        `${missing.join(', ')} ${missing.length > 1 ? 'are' : 'is'} not on PATH. ` +
+        `${hint === undefined ? 'Install it' : `Install it (${hint})`}, or drop this target — the other ` +
+        `formats need no tools at all. \`gjsify ship --stage\` also works without ${missing.join('/')}: ` +
+        'the payload is assembled by this CLI and only the container needs them.');
+}
 /** Parse `--target deb,rpm` into a sorted, deduplicated descriptor list. */
 export function resolveFormats(raw) {
     const names = raw

package/lib/utils/ship/settings.js

@@ -12,6 +12,7 @@
 import { validateMimeTypes } from './mime.js';
 import { basename } from 'node:path';
 import { DEFAULT_GJS_FLOOR } from './depends.js';
+import { resolveShipFlatpakSettings } from './flatpak-config.js';
 import { assertRelease, normaliseVersion } from './version.js';
 /** Freedesktop main category → deb `Section:` / rpm `Group:`. First match wins. */
 const CATEGORY_SECTIONS = [
@@ -71,6 +72,11 @@ export function resolveShipSettings(input) {
         warnings.push(`gjsify ship: no icon found — the installed app will show a placeholder in menus and app stores. ` +
             'Point `gjsify.ship.icon` at an SVG (or a directory of sized PNGs).');
     }
+    // Resolved here rather than in the packer, because the packer may run on a
+    // host with no `package.json` at all (ADR 0024 § A2) — and because the
+    // finish-args default depends on `kind`, which is a project fact.
+    const flatpakSettings = resolveShipFlatpakSettings({ ship, flatpak, kind });
+    warnings.push(...flatpakSettings.warnings);
     const settings = {
         projectDir: input.projectDir,
         appId,
@@ -101,6 +107,7 @@ export function resolveShipSettings(input) {
         outDir: input.cli.outDir ?? ship.outDir ?? 'ship',
         arch: input.cli.arch ?? process.arch,
         minGjsVersion: ship.minGjsVersion ?? DEFAULT_GJS_FLOOR,
+        flatpak: flatpakSettings.settings,
     };
     return { settings, metadata, warnings };
 }

package/lib/utils/ship/stage-manifest.d.ts

@@ -10,8 +10,14 @@ export declare const STAGE_MANIFEST_FILE = ".gjsify-ship-stage.json";
  * Bump it whenever a field's MEANING changes, not when one is added that an
  * older reader would simply ignore; a reader that ignores a field it does not
  * know is exactly how a mode plan silently loses an entry.
+ *
+ * 2 added `settings.appId` and `settings.flatpak` for the Flatpak target. That
+ * is the second case and not the first: an older reader ignoring
+ * `settings.flatpak` would not skip a field, it would pack a Flatpak against
+ * whatever runtime IT defaults to — a different `org.gnome.Platform` version
+ * than the project asked for, at exit 0.
  */
-export declare const STAGE_SCHEMA_VERSION = 1;
+export declare const STAGE_SCHEMA_VERSION = 2;
 /**
  * The OS whose layout `planStage` produces.
  *
@@ -72,7 +78,10 @@ export interface StageManifestInput {
  * `extraFiles` and `licenseFile` — seven absolute paths from the assembling
  * host — into a file whose whole purpose is to be read somewhere else. The
  * explicit list is also what makes adding a field a decision: see the comment
- * on {@link PackSettings} for what belongs on each side.
+ * on {@link PackSettings} for what belongs on each side. `appId` and `flatpak`
+ * were that decision for the Flatpak target, and the `--from-stage` e2e is
+ * where an omission would have shown: it deletes the project, so a field the
+ * packer needs and the manifest lacks has nowhere to be read from.
  */
 export declare function toPackSettings(settings: ShipSettings): PackSettings;
 /** Absolute path of a stage's manifest. */

package/lib/utils/ship/stage-manifest.js

@@ -49,8 +49,14 @@ export const STAGE_MANIFEST_FILE = '.gjsify-ship-stage.json';
  * Bump it whenever a field's MEANING changes, not when one is added that an
  * older reader would simply ignore; a reader that ignores a field it does not
  * know is exactly how a mode plan silently loses an entry.
+ *
+ * 2 added `settings.appId` and `settings.flatpak` for the Flatpak target. That
+ * is the second case and not the first: an older reader ignoring
+ * `settings.flatpak` would not skip a field, it would pack a Flatpak against
+ * whatever runtime IT defaults to — a different `org.gnome.Platform` version
+ * than the project asked for, at exit 0.
  */
-export const STAGE_SCHEMA_VERSION = 1;
+export const STAGE_SCHEMA_VERSION = 2;
 /**
  * The OS whose layout `planStage` produces.
  *
@@ -69,11 +75,15 @@ export const STAGE_LAYOUT_OS = 'linux';
  * `extraFiles` and `licenseFile` — seven absolute paths from the assembling
  * host — into a file whose whole purpose is to be read somewhere else. The
  * explicit list is also what makes adding a field a decision: see the comment
- * on {@link PackSettings} for what belongs on each side.
+ * on {@link PackSettings} for what belongs on each side. `appId` and `flatpak`
+ * were that decision for the Flatpak target, and the `--from-stage` e2e is
+ * where an omission would have shown: it deletes the project, so a field the
+ * packer needs and the manifest lacks has nowhere to be read from.
  */
 export function toPackSettings(settings) {
     return {
         binaryName: settings.binaryName,
+        appId: settings.appId,
         version: settings.version,
         release: settings.release,
         maintainer: settings.maintainer,
@@ -86,6 +96,7 @@ export function toPackSettings(settings) {
         extraDepends: settings.extraDepends,
         typelibPackages: settings.typelibPackages,
         minGjsVersion: settings.minGjsVersion,
+        flatpak: settings.flatpak,
     };
 }
 /** Absolute path of a stage's manifest. */
@@ -355,6 +366,7 @@ function readPackSettings(data, at) {
     const typelibPackages = record(data.typelibPackages, field('typelibPackages'));
     return {
         binaryName: expectString(data.binaryName, field('binaryName')),
+        appId: expectString(data.appId, field('appId')),
         version: expectString(data.version, field('version')),
         release: expectString(data.release, field('release')),
         maintainer: expectString(data.maintainer, field('maintainer')),
@@ -379,6 +391,31 @@ function readPackSettings(data, at) {
             ];
         })),
         minGjsVersion: expectString(data.minGjsVersion, field('minGjsVersion')),
+        flatpak: readFlatpakSettings(record(data.flatpak, field('flatpak')), field('flatpak')),
+    };
+}
+/**
+ * The Flatpak half, validated the same way as everything else here.
+ *
+ * Every field is required and none is defaulted, deliberately: a `?? []` on
+ * `finishArgs` would turn a mutilated manifest into an app with no display
+ * socket — it installs, it starts, and it draws nothing. The defaults belong on
+ * the assembling host, where `gjsify.ship` and `kind` are in reach; by the time
+ * a manifest exists the answer has already been decided and writing it down
+ * twice is how the two hosts disagree.
+ */
+function readFlatpakSettings(data, at) {
+    const field = (name) => `${at}.${name}`;
+    const strings = (value, name) => expectArray(value, field(name)).map((entry, index) => expectString(entry, field(`${name}[${index}]`)));
+    return {
+        runtime: expectString(data.runtime, field('runtime')),
+        runtimeVersion: expectString(data.runtimeVersion, field('runtimeVersion')),
+        sdk: expectString(data.sdk, field('sdk')),
+        branch: expectString(data.branch, field('branch')),
+        sdkExtensions: strings(data.sdkExtensions, 'sdkExtensions'),
+        appendPath: strings(data.appendPath, 'appendPath'),
+        finishArgs: strings(data.finishArgs, 'finishArgs'),
+        cleanup: strings(data.cleanup, 'cleanup'),
     };
 }
 function record(value, at) {

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

@@ -36,7 +36,71 @@ export interface ShipArtifact {
     /** Size in bytes. */
     size: number;
 }
-export type FormatId = 'deb' | 'rpm';
+export type FormatId = 'deb' | 'rpm' | 'flatpak';
+/**
+ * The formats whose ARTIFACT carries a distro dependency list.
+ *
+ * Not every `FormatId`, and this is where the difference is written down once
+ * instead of being rediscovered per call site. A `.deb` says
+ * `Depends: gir1.2-gtk-4.0`, an `.rpm` says `Requires: gtk4`, and both are
+ * package names in a distribution's namespace. A Flatpak has no such field: it
+ * declares ONE dependency, its runtime (`org.gnome.Platform//50`), in the
+ * manifest — and inside that runtime a typelib is either present or nothing on
+ * the system provides it, so there is no package to name and no gap a name
+ * could close.
+ *
+ * `Extract<…>` rather than a fresh literal union, so this cannot outlive
+ * `FormatId`: dropping a member there shrinks this and reds every table keyed on
+ * it. The other direction is covered by {@link FormatDescriptor.depends} being
+ * REQUIRED — a new format cannot be added without saying which side it is on.
+ */
+export type DistroFormatId = Extract<FormatId, 'deb' | 'rpm'>;
+/** An operating system in the repo-wide `process.platform` spelling (root AGENTS.md § Runtime & platform model). */
+export type HostOs = 'linux' | 'darwin' | 'win32';
+/**
+ * Where a format can be FINISHED, and who can read the result back (ADR 0024 § A3).
+ *
+ * Three fields rather than one `hostOs`, because the three questions have
+ * different answers. `finishOn` is not the LAYOUT — a `<App>.app` tree is
+ * assembled anywhere while the `.dmg` around it needs macOS. `requiredTools` is
+ * not implied by `finishOn` — `.deb` and `.rpm` are written by this tree and
+ * exec nothing, which is the whole reason `rpm` could become an independent
+ * oracle and catch the dpkg-`$1` defect in the first artifact. And `oracle` is
+ * derivable from neither: a format built by the platform's own tool forfeits
+ * that independence unless a reader from a DIFFERENT implementation family
+ * exists, which is exactly what `selfReading` is the honest confession of.
+ */
+export interface HostRequirement {
+    /** OSes whose tooling can finish this format. `'any'` = pure JS, under GJS, offline. */
+    finishOn: 'any' | readonly HostOs[];
+    /** Commands the packer EXECS. Empty iff this tree writes the format itself. */
+    requiredTools: readonly string[];
+    /**
+     * How to install {@link requiredTools}, in this format's own words.
+     *
+     * DATA, because the refusal that names it is one generic function. The
+     * first cut hardcoded `sudo dnf install flatpak flatpak-builder` inside
+     * `assertToolsInstalled`, which is correct for exactly one format and would
+     * have told the first `.dmg` or `.msi` user to install flatpak — from the
+     * same branchless dispatch this whole table exists to keep branchless.
+     * Required whenever `requiredTools` is non-empty; `flatpak.spec.ts` holds
+     * that, the same way it holds `selfReading`.
+     */
+    installHint?: string;
+    oracle: {
+        /** Readers from a DIFFERENT implementation family than the packer. */
+        readWith: readonly string[];
+        /** Where each reader runs. A Linux-runnable reader is worth more — every CI leg has one. */
+        readOn: readonly HostOs[];
+        /**
+         * No independent discriminator yet. Legal to DECLARE while a format is
+         * being built; illegal to release — `flatpak.spec.ts` is what turns that
+         * sentence into a red test, so flipping it is a decision somebody makes
+         * rather than a field nobody reads.
+         */
+        selfReading: boolean;
+    };
+}
 /**
  * Everything that is per-FORMAT, as data.
  *
@@ -48,6 +112,13 @@ export interface FormatDescriptor {
     id: FormatId;
     /** Install prefix the format's contents hang under. */
     prefix: string;
+    /** Where this format can be packed, what it execs, and who reads it back. */
+    host: HostRequirement;
+    /**
+     * The key this format's dependency list is spelled under, or `null` when its
+     * dependencies are not a package list at all — see {@link DistroFormatId}.
+     */
+    depends: DistroFormatId | null;
     /** Where the project's licence text goes in this format's overlay. */
     licenseDest: (binaryName: string) => string;
     /**
@@ -109,8 +180,12 @@ export interface ShipMimeType {
  *    `share/locale/<rel>`, and no packer reads the field. So translations
  *    cross in the payload, where they belong, and the `abs` path does not
  *    cross at all. This list being explicit is what caught that.
- *  - `appId`, `name`, `kind`, `execArgs` — read by the planner and the metadata
- *    renderers, all of which have run by the time a stage exists.
+ *  - `name`, `kind`, `execArgs` — read by the planner and the metadata
+ *    renderers, all of which have run by the time a stage exists. `appId` was
+ *    on this line and MOVED: the Flatpak packer needs it at pack time twice
+ *    over — it is the manifest's `id` and the ref `flatpak build-bundle`
+ *    exports — and neither is derivable from the payload, because the desktop
+ *    entry that carries the id is only staged for `kind: 'app'`.
  *  - `arch` — carried by the manifest's `target`, which is also the value a
  *    mismatched stage is refused on, so it lives in exactly one place.
  *  - `mimeTypes` — phase 1 renders the shared-mime-info document into the
@@ -121,6 +196,8 @@ export interface ShipMimeType {
 export interface PackSettings {
     /** Package name: the `bin/` entry, the deb `Package:`, the rpm `Name:`. */
     binaryName: string;
+    /** Reverse-DNS application id — the Flatpak manifest's `id` and the exported ref. */
+    appId: string;
     /** Upstream version, normalised for package managers. */
     version: string;
     /** Package revision within one upstream version (deb revision / rpm release). */
@@ -139,24 +216,50 @@ export interface PackSettings {
     /** rpm `Group:`. */
     group: string;
     /** Extra runtime dependencies per format, appended to the derived set. */
-    extraDepends: {
-        deb: string[];
-        rpm: string[];
-    };
+    extraDepends: Record<DistroFormatId, string[]>;
     /** Project-supplied GI-namespace → package rows, filling gaps in the built-in table. */
-    typelibPackages: Record<string, {
-        deb: string;
-        rpm: string;
-    }>;
+    typelibPackages: Record<string, Record<DistroFormatId, string>>;
     /** Minimum GJS the emitted dependency asks for. */
     minGjsVersion: string;
+    /** The Flatpak manifest's non-payload half, fully defaulted at stage time. */
+    flatpak: ShipFlatpakSettings;
+}
+/**
+ * What the generated Flatpak manifest says about everything that is not the payload.
+ *
+ * Resolved — defaults applied — while the project is still in reach, because
+ * the defaults depend on `kind` and on `gjsify.flatpak`/`gjsify.ship.flatpak`,
+ * and the finishing host has neither.
+ *
+ * There is deliberately no `modules` / `extraModules` here. Under `ship` the
+ * module list IS the staged payload (ADR 0024 § 2: "a target that needs an
+ * extra file gets an overlay, never a branch in the staging code"), and an
+ * escape hatch that injects arbitrary build modules would put a second staging
+ * model back in the tree — which is the one thing § 8 gates the whole migration
+ * on. A project that genuinely needs to BUILD something inside the sandbox
+ * still has `gjsify flatpak init` + `gjsify flatpak build`, unchanged.
+ */
+export interface ShipFlatpakSettings {
+    /** Runtime id, e.g. `org.gnome.Platform`. */
+    runtime: string;
+    /** Runtime/SDK version, e.g. `50`. */
+    runtimeVersion: string;
+    /** SDK id, e.g. `org.gnome.Sdk`. */
+    sdk: string;
+    /** The branch the app is exported under — the last segment of `app/<id>/<arch>/<branch>`. */
+    branch: string;
+    sdkExtensions: string[];
+    /** Path components prepended to `PATH` inside the build sandbox. */
+    appendPath: string[];
+    /** Capabilities the finished app is granted. */
+    finishArgs: string[];
+    /** Cleanup globs applied to `/app` after the module has run. */
+    cleanup: string[];
 }
 /** The resolved, fully defaulted configuration for one `gjsify ship` run. */
 export interface ShipSettings extends PackSettings {
     /** Absolute path to the project being shipped. */
     projectDir: string;
-    /** Reverse-DNS application id — desktop entry, metainfo and icon basename. */
-    appId: string;
     /** Human-readable display name. */
     name: string;
     /** Absolute path to the licence file, when one was found. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.43.0",
+    "version": "0.44.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -142,21 +142,21 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.43.0",
-        "@gjsify/create-app": "^0.43.0",
-        "@gjsify/node-globals": "^0.43.0",
-        "@gjsify/node-polyfills": "^0.43.0",
-        "@gjsify/npm-registry": "^0.43.0",
-        "@gjsify/resolve-npm": "^0.43.0",
-        "@gjsify/rolldown-plugin-gjsify": "^0.43.0",
-        "@gjsify/vite-plugin-blueprint": "^0.43.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.43.0",
-        "@gjsify/semver": "^0.43.0",
-        "@gjsify/tar": "^0.43.0",
-        "@gjsify/tsc": "^0.43.0",
-        "@gjsify/utils": "^0.43.0",
-        "@gjsify/web-polyfills": "^0.43.0",
-        "@gjsify/workspace": "^0.43.0",
+        "@gjsify/buffer": "^0.44.0",
+        "@gjsify/create-app": "^0.44.0",
+        "@gjsify/node-globals": "^0.44.0",
+        "@gjsify/node-polyfills": "^0.44.0",
+        "@gjsify/npm-registry": "^0.44.0",
+        "@gjsify/resolve-npm": "^0.44.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.44.0",
+        "@gjsify/vite-plugin-blueprint": "^0.44.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.44.0",
+        "@gjsify/semver": "^0.44.0",
+        "@gjsify/tar": "^0.44.0",
+        "@gjsify/tsc": "^0.44.0",
+        "@gjsify/utils": "^0.44.0",
+        "@gjsify/web-polyfills": "^0.44.0",
+        "@gjsify/workspace": "^0.44.0",
         "acorn": "^8.17.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
@@ -165,13 +165,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.43.0",
+        "@gjsify/unit": "^0.44.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.43.0",
-        "@gjsify/rolldown-native": "^0.43.0"
+        "@gjsify/oxfmt-native": "^0.44.0",
+        "@gjsify/rolldown-native": "^0.44.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {