@gjsify/cli 0.42.0 → 0.44.0

package/lib/utils/onboard-probe.js

@@ -11,6 +11,43 @@
 import { DEFAULT_REGISTRY, registryFor } from '@gjsify/npm-registry';
 import { classifyTrustList, trustUrl } from './trust-registry.js';
 export const PROBE_RETRY_DELAY_MS = 400;
+/**
+ * Does the registry serve a packument for this name?
+ *
+ * THE ORACLE, and the reason it exists: npm's trust endpoint answers `2xx` with an
+ * EMPTY LIST for a name that was never published. `classifyTrustList` reads that as
+ * `untrusted`, so `gjsify onboard` planned "already on npm, just needs trust" for a
+ * package that did not exist — it trusted the name, reported `0 to publish+trust`
+ * and published NOTHING. A bootstrap command reporting its own gap as closed, and
+ * it is why the v0.36.0 repair failed twice before anyone looked at the registry.
+ *
+ * `GET <registry>/<name>` is unauthenticated and needs no OTP, so it answers in the
+ * one situation that matters: a `--dry-run` before the maintainer has an OTP to
+ * hand, where every trust read is `401` and the plan is otherwise empty.
+ *
+ * `null` means UNDECIDED (network or an unexpected status) — never "absent". A
+ * bootstrap that publishes on a failed probe is worse than one that reports blocked.
+ */
+export async function packumentExists(registry, name) {
+    const base = registry.endsWith('/') ? registry.slice(0, -1) : registry;
+    try {
+        // `Accept` narrows the response to the abbreviated packument: the full one
+        // for a package like `@gjsify/cli` is megabytes, and existence is all we ask.
+        const res = await fetch(`${base}/${name.replace('/', '%2f')}`, {
+            method: 'GET',
+            headers: { accept: 'application/vnd.npm.install-v1+json' },
+        });
+        if (res.status === 404)
+            return false;
+        if (res.ok)
+            return true;
+        return null;
+    }
+    catch {
+        // A DNS or TLS failure is not evidence of absence.
+        return null;
+    }
+}
 /** Default probe concurrency — kept SMALL so a single token never bursts npm. */
 export const DEFAULT_PROBE_CONCURRENCY = 4;
 /** Map a classified trust state to the action the onboard sweep should take. */
@@ -48,6 +85,34 @@ export async function probeTrustState(request, ws, ctx, opts = {}) {
         res = await request('GET', url);
         state = classifyTrustList(res.status, res.json, classifyOpts);
     }
+    // `untrusted` is the ONE ambiguous answer: the trust endpoint returns `2xx` with
+    // an empty list both for "published, nobody trusted it" and for "no such name".
+    // Only that case pays for the extra read — `trusted` cannot be a missing package
+    // and `unpublished` already has its answer.
+    // Two questions, two endpoints. The trust list answers "who may publish this",
+    // and onboard also needs "does this name exist at all" — which it can only
+    // INFER from the trust list, and infers wrongly in both ambiguous states:
+    //
+    //   untrusted      npm serves 2xx and an EMPTY list for a name that was never
+    //                  published — byte-identical to a real package that simply has
+    //                  no trusted publisher configured.
+    //   auth-required  a 401 says nothing whatsoever about existence. It is also
+    //                  where EVERY package lands in a `--dry-run` run before the
+    //                  maintainer has an OTP to hand, which is exactly the moment
+    //                  the plan is being read to decide whether to proceed.
+    //
+    // The packument answers the question directly and unauthenticated, and a 404
+    // there is proof no OTP could change. Only these two states pay for the extra
+    // read: `trusted` cannot be a missing package, and `unpublished` already has
+    // its answer from the endpoint it just asked.
+    if (state === 'untrusted' || state === 'auth-required') {
+        const exists = await (opts.exists ?? packumentExists)(registry, ws.name);
+        // ONLY a definitive 404 reclassifies. `null` — network failure, unexpected
+        // status — leaves the state exactly as it was: a bootstrap that publishes
+        // on a failed read is worse than one that reports itself blocked.
+        if (exists === false)
+            state = 'unpublished';
+    }
     return { ws, registry, url, state, httpStatus: res.status, action: actionForState(state) };
 }
 /**

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

@@ -1,7 +1,7 @@
-import type { PayloadEntry } from './payload.js';
-import type { ShipSettings } from './types.js';
+import { type PayloadEntry } from './payload.js';
+import type { PackSettings } from './types.js';
 export interface DebInputs {
-    settings: ShipSettings;
+    settings: PackSettings;
     /** The staged payload, prefix-relative. */
     payload: readonly PayloadEntry[];
     /** Install prefix, e.g. `/usr`. */

package/lib/utils/ship/deb.js

@@ -20,8 +20,9 @@ import { createArArchive } from './ar.js';
 import { formatDebDepend } from './depends.js';
 import { gzipDeterministic } from './gzip.js';
 import { renderDebScripts } from './scripts.js';
+import { readPayloadFacts } from './payload.js';
 export async function buildDeb(inputs) {
-    const { settings, payload, mtime } = inputs;
+    const { payload, mtime } = inputs;
     const prefix = inputs.prefix.replace(/^\/+/, '');
     const named = payload.map((entry) => ({ ...entry, tarPath: `./${posix.join(prefix, entry.path)}` }));
     const directories = ancestorDirectories(named.map((entry) => entry.tarPath));
@@ -44,7 +45,10 @@ export async function buildDeb(inputs) {
         { name: './control', body: control, mode: 0o644, mtime },
         { name: './md5sums', body: md5sums, mode: 0o644, mtime },
     ];
-    const maintainerScripts = renderDebScripts(settings, inputs.prefix);
+    // From the PAYLOAD, not the settings: the maintainer scripts refresh exactly the
+    // directories this package wrote into, and since ADR 0024 § A2 this packer also runs on a
+    // host that has the staged tree and no project to ask.
+    const maintainerScripts = renderDebScripts(readPayloadFacts(payload), inputs.prefix);
     for (const [name, body] of Object.entries(maintainerScripts)) {
         // dpkg refuses a maintainer script outside 0555–0775 with the mode in
         // the error, so this is 0755 rather than "whatever the source had".

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,25 +14,25 @@ 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";
-/**
- * Warn when the derived floor cannot be satisfied by a released Debian.
- * Returns the warning lines; empty when the floor is fine.
- */
-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[];
-    /** `'app'` installs a desktop entry and icons; `'cli'` does not. */
-    kind: 'app' | 'cli';
+    /**
+     * Whether the payload installs into `share/icons/hicolor/`.
+     *
+     * Was `kind: 'app' | 'cli'`, which is a proxy for the question and not the question:
+     * `hicolor-icon-theme` is depended on because it OWNS that directory, so an app that
+     * installs no icon used to declare a dependency it never touched. Derived from the payload
+     * (`readPayloadFacts`), which is also the only thing the packing host has (ADR 0024 § A2).
+     */
+    hasIcons: boolean;
     /** Whether the payload installs GSettings schemas. */
     hasSchemas: boolean;
     /** 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.
@@ -46,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

@@ -35,14 +35,34 @@
  * is how a project whose bundle really does run on older GJS lowers it.
  */
 export const DEFAULT_GJS_FLOOR = '1.86';
+/**
+ * The package providing `glib-compile-schemas`, per format.
+ *
+ * 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 `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}. */
 const DEBIAN_GJS = 'trixie ships 1.82.3 and forky 1.88.1; 1.84 and 1.86 were skipped';
 /**
  * Warn when the derived floor cannot be satisfied by a released Debian.
  * Returns the warning lines; empty when the floor is fine.
  */
+/**
+ * Which formats this Debian-suite warning is ABOUT.
+ *
+ * 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 `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.
+ */
+const GJS_FLOOR_IS_DEBIAN_NEWS = { deb: true, rpm: false };
 export function warnAboutGjsFloor(format, floor) {
-    if (format !== 'deb')
+    if (!GJS_FLOOR_IS_DEBIAN_NEWS[format])
         return [];
     // Only a floor forky ACTUALLY satisfies is quiet. The first cut tested
     // `>= 1.88.1` and therefore went silent for 1.90 and 2.0 as well — the
@@ -171,7 +191,9 @@ export function deriveDepends(format, inputs) {
             'have to. (`gjsify.ship.depends.<format>` is for dependencies that are not typelibs at all — it ' +
             'appends, and deliberately does not silence this.)');
     }
-    if (inputs.kind === 'app')
+    // The package that owns `/usr/share/icons/hicolor` — so this follows the icons, not the
+    // app/cli distinction that used to stand in for them.
+    if (inputs.hasIcons)
         out.push('hicolor-icon-theme');
     // The package that ships `glib-compile-schemas`, NOT `gsettings-desktop-schemas`
     // (which ships GNOME's own `org.gnome.desktop.*` schemas and has nothing to
@@ -182,7 +204,7 @@ export function deriveDepends(format, inputs) {
     // `Gio.Settings.new()` aborts the app — an install that succeeds and an app
     // that does not start.
     if (inputs.hasSchemas)
-        out.push(format === 'deb' ? 'libglib2.0-bin' : 'glib2');
+        out.push(SCHEMA_COMPILER_PACKAGE[format]);
     out.push(...inputs.extra);
     // Set-dedupe keeps first-insertion order, so `gjs` stays first and the
     // list is stable across runs.

package/lib/utils/ship/discover.js

@@ -4,8 +4,8 @@
 // so `settings.ts` and `plan.ts` can stay pure. Every probe has a configured
 // override; the probes exist so a project that follows the GNOME convention
 // (`data/icons/hicolor/…`, `data/*.gschema.xml`) needs no configuration at all.
-import { existsSync, readdirSync, statSync } from 'node:fs';
-import { isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
 import { LICENSE_FILE_NAMES } from './settings.js';
 const ICON_EXTENSIONS = ['.svg', '.png'];
 export function discoverPayload(input) {
@@ -189,6 +189,34 @@ function discoverSchemas(projectDir, configured) {
     }
     return [];
 }
+/**
+ * The licence text this package ships — searched UP the tree, not just beside
+ * `package.json`.
+ *
+ * A monorepo package does not carry its own copy. `packages/infra/cli`
+ * declares `"license": "MIT"` and the text lives one `LICENSE` up at the
+ * repository root, shared by sixty-odd packages; searching `projectDir` alone
+ * found nothing, `planOverlay` turned "nothing" into an empty overlay, and the
+ * `.deb` shipped without the `/usr/share/doc/<pkg>/copyright` that Debian
+ * Policy § 12.5 requires. Nothing downstream noticed: `dpkg-deb --info` prints
+ * a clean control file and `dpkg -i` installs it. It took the first leg that
+ * ran a real `lintian` to say so.
+ *
+ * WHERE THE SEARCH STOPS is the whole design. It climbs to the first ancestor
+ * that is a project root — one holding `.git`, or a `package.json` declaring
+ * `workspaces` — and searches that directory too, then stops. Above that line
+ * a `LICENSE` belongs to some unrelated tree that happens to be a parent
+ * directory (`~/Projekte/LICENSE` is not yours), and packaging its text would
+ * make a specific false legal claim. When NO marker is found the search is the
+ * project directory alone: without a marker there is no way to tell where the
+ * project ends, and guessing wrong is the same false claim.
+ *
+ * What this cannot check is whether the inherited text is the RIGHT licence
+ * for this package — an Apache-2.0 package inside an MIT monorepo would
+ * inherit the wrong one. Reading an SPDX identifier out of licence prose is
+ * not something to guess at, so the caller PRINTS the inherited path instead
+ * (see `commands/ship.ts`), and `gjsify.ship.licenseFile` overrides it.
+ */
 function discoverLicense(projectDir, configured) {
     if (configured !== undefined) {
         const target = resolve(projectDir, configured);
@@ -197,13 +225,51 @@ function discoverLicense(projectDir, configured) {
         }
         return target;
     }
-    for (const name of LICENSE_FILE_NAMES) {
-        const target = join(projectDir, name);
-        if (existsSync(target))
-            return target;
+    for (const dir of licenseSearchDirs(projectDir)) {
+        for (const name of LICENSE_FILE_NAMES) {
+            const target = join(dir, name);
+            if (existsSync(target))
+                return target;
+        }
     }
     return undefined;
 }
+/** `projectDir` first, then each ancestor up to and including the project root. */
+function licenseSearchDirs(projectDir) {
+    const dirs = [];
+    for (let current = projectDir;;) {
+        dirs.push(current);
+        if (isProjectRoot(current))
+            return dirs;
+        const parent = dirname(current);
+        if (parent === current)
+            return [projectDir];
+        current = parent;
+    }
+}
+/**
+ * Is this the top of the tree the project belongs to?
+ *
+ * `.git` is tested with `existsSync` rather than `statSync().isDirectory()`
+ * because in a git WORKTREE it is a file, and this repository is developed in
+ * worktrees.
+ */
+function isProjectRoot(dir) {
+    if (existsSync(join(dir, '.git')))
+        return true;
+    const manifest = join(dir, 'package.json');
+    if (!existsSync(manifest))
+        return false;
+    try {
+        return JSON.parse(readFileSync(manifest, 'utf-8')).workspaces !== undefined;
+    }
+    catch {
+        // A malformed `package.json` in some ancestor is not this command's
+        // business, and it must not turn a licence search into a ship failure.
+        // Not a root, then: the climb continues and `.git` still stops it.
+        return false;
+    }
+}
 /**
  * Every regular file under `dir`, as POSIX-separated relative paths.
  *

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>;