@gjsify/cli 0.43.0 → 0.45.0

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 with ${describeExit(result)}.`);
+    }
+}

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

@@ -1,5 +1,118 @@
-import type { FormatDescriptor, FormatId } from './types.js';
+import { type Layout } from './layout.js';
+import type { FormatDescriptor, FormatId, HostOs, PackSettings, RequiredTools } from './types.js';
+/**
+ * The directory `windows-dir` produces, and the top level `windows-dir-zip` puts
+ * its entries under.
+ *
+ * ONE function with TWO readers, deliberately: the zip has to expand to the same
+ * directory the other row writes, and two literals would be two names a user is
+ * asked to believe are one.
+ */
+export declare function windowsProgramDirName(settings: PackSettings): string;
+/**
+ * The tools ONE host needs for a format, whichever shape the row declares.
+ *
+ * The one place the union in {@link RequiredTools} is opened, so a caller cannot
+ * read the map and get `undefined.filter` or read the array on a row that has a
+ * map. An OS the map does not name answers `[]` — not because nothing is needed
+ * there, but because {@link assertHostCanFinish} has already refused that host by
+ * the time this is asked, and inventing a tool list for a host that cannot finish
+ * the format would answer a question nobody may ask.
+ */
+export declare function requiredToolsOn(tools: RequiredTools, host: string): readonly string[];
+/**
+ * Every tool any host could need for a format — the question `installHint`'s
+ * presence is gated on.
+ *
+ * Deliberately NOT what {@link assertToolsInstalled} checks. "Does this row need a
+ * hint at all" is a property of the ROW; "is this tool here" is a question about
+ * one machine, and answering the first with the second would let a row declare a
+ * Windows-only tool and no hint, because the gate happened to run on Linux.
+ */
+export declare function allRequiredTools(tools: RequiredTools): readonly string[];
 export declare const FORMATS: Record<FormatId, FormatDescriptor>;
 export declare const FORMAT_IDS: FormatId[];
-/** Parse `--target deb,rpm` into a sorted, deduplicated descriptor list. */
-export declare function resolveFormats(raw: readonly string[]): FormatDescriptor[];
+/**
+ * What `gjsify ship <os>` builds when nothing said otherwise — every format that
+ * wraps THAT OS's layout and 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.
+ *
+ * `layoutOs` is the SECOND criterion, and it is what the layout axis needed: a
+ * `.app` and its zip and a Windows program directory are all `finishOn: 'any'`,
+ * so on the one criterion a bare `gjsify ship` on Linux would start emitting
+ * five artifacts (ADR 0024 issue #1354, open question 3). Answered with § A2's
+ * positional rather than instead of it — the positional picks the layout, this
+ * picks the formats that wrap it, and `gjsify ship` on Linux keeps emitting
+ * exactly `deb` and `rpm`.
+ *
+ * An EMPTY answer is legal and is what darwin and windows give today: their
+ * layouts assemble (`--stage`) and no format wraps them yet. `assemble` refuses
+ * a pack with nothing to pack rather than exiting 0 having produced no artifact.
+ */
+export declare function defaultFormatIds(layoutOs: HostOs): FormatId[];
+/** Every format that wraps one OS's layout, tool-bound ones included. */
+export declare function formatIdsFor(layoutOs: HostOs): 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, host?: string): void;
+/**
+ * Parse an explicit `--target deb,rpm` into a sorted, deduplicated descriptor list.
+ *
+ * A format belonging to another layout is an ERROR here, not a filter:
+ * `gjsify ship darwin --target deb` is a mistake worth naming, and dropping it
+ * silently would stage the darwin layout, pack nothing and exit 0 — the shape
+ * the empty-list refusal above already exists to prevent, arriving through a
+ * different door.
+ *
+ * The FLAG is what makes that the right answer, and it is the whole difference
+ * from {@link configuredFormats}: a value typed on this command line is a claim
+ * about THIS run.
+ */
+export declare function resolveFormats(raw: readonly string[], layout: Layout): FormatDescriptor[];
+/**
+ * The same names from `gjsify.ship.targets`, FILTERED to the current layout.
+ *
+ * A configured list is a project-level DEFAULT — "when I ship this, build these"
+ * — written once and read by every run, so it cannot be a claim about a layout
+ * the author had not heard of when they wrote it. Refusing it the way
+ * {@link resolveFormats} refuses a flag makes the new positional unusable in
+ * every project that has the key, and this repository is the proof: with
+ * `targets: ["deb", "rpm"]` in `packages/infra/cli/package.json`,
+ * `gjsify ship darwin --stage` exited 1 telling the author to run
+ * `gjsify ship darwin --stage`. There was no `--target` value that got a darwin
+ * stage out of such a project at all.
+ *
+ * Filtering is safe HERE and only here, because an empty result is not a silent
+ * success: `assemble` refuses a PACK with nothing to pack, and a `--stage` run
+ * legitimately wants exactly this — assemble the layout, wrap nothing.
+ */
+export declare function configuredFormats(raw: readonly string[], layout: Layout): {
+    formats: FormatDescriptor[];
+    dropped: FormatId[];
+};