@gjsify/cli 0.50.0 → 0.51.1

package/lib/commands/ship.js

@@ -32,14 +32,15 @@ import { buildDeb } from '../utils/ship/deb.js';
 import { deriveDepends, warnAboutGjsFloor, warnAboutNodeFloor } from '../utils/ship/depends.js';
 import { isGtkRuntimeTarget, stageAppRuntime } from '../utils/ship/app-runtime.js';
 import { discoverPayload } from '../utils/ship/discover.js';
+import { appDirFor, appDirPayload, appImageHostRequirements, appImageRuntimeNotice, buildAppImage, findPinnedRuntime, stampAppDirTimes, } from '../utils/ship/appimage.js';
 import { buildDmgImage, dmgVolumeDir, dmgVolumeName } from '../utils/ship/dmg.js';
 import { buildFlatpakBundle } from '../utils/ship/flatpak.js';
 import { localizeMetadata } from '../utils/ship/localize-metadata.js';
-import { assertHostCanFinish, assertToolsInstalled, canCarryTicket, configuredFormats, defaultFormatIds, formatIdsFor, resolveFormats, windowsProgramDirName, FORMAT_IDS, FORMATS, } from '../utils/ship/formats.js';
+import { assertHostCanFinish, assertKindCanPack, assertToolsInstalled, canCarryTicket, configuredFormats, defaultFormatIds, formatIdsFor, resolveFormats, windowsProgramDirName, FORMAT_IDS, FORMATS, } from '../utils/ship/formats.js';
 import { assertLayoutSupportsArch, hostLayout, layoutForOs, place, placeStage, resolveLayout, LAYOUT_NAMES, } from '../utils/ship/layout.js';
 import { isNodeRuntimeTarget, resolveNodeRuntime } from '../utils/ship/node-runtime.js';
 import { isUnder, SHARE } from '../utils/ship/share-dirs.js';
-import { compileSchemasForStage } from '../utils/ship/schemas.js';
+import { compileSchemasForPayload, compileSchemasForStage } from '../utils/ship/schemas.js';
 import { buildMsi, MSI_PAYLOAD_DIR } from '../utils/ship/msi.js';
 import { buildZip, zipEntriesFromPayload } from '../utils/ship/zip.js';
 import { assertEntryRunsUnder } from '../utils/ship/entry-interpreter.js';
@@ -49,7 +50,7 @@ import { assertOverlayIsLicensed, planOverlay, planStage } from '../utils/ship/p
 import { assertHostCanSign, notarizeArtifact, stapleArtifact, resolveNotaryPlan, resolveSignPlan, signPayload, } from '../utils/ship/signing.js';
 import { renderLauncher } from '../utils/ship/launcher.js';
 import { buildRpm } from '../utils/ship/rpm.js';
-import { resolveShipApp, resolveShipBundle, resolveShipSettings, } from '../utils/ship/settings.js';
+import { resolveShipApp, resolveShipBundle, resolveShipKind, resolveShipSettings, } from '../utils/ship/settings.js';
 import { assertExpectedTarget, assertFormatsStaged, formatTarget, overlayFiles, readStageManifest, resolveStageMtime, warnOnToolSkew, writeStageManifest, STAGE_MANIFEST_FILE, } from '../utils/ship/stage-manifest.js';
 import { directorySize, readStage, writePayload, writeStage } from '../utils/ship/stage-writer.js';
 const LOG = '[gjsify ship]';
@@ -276,6 +277,23 @@ async function assemble(args) {
     // afterwards costs the whole build for a refusal that was knowable up
     // front. Skipped under `--stage`, which is precisely the phase that does
     // NOT need the format's tooling — that asymmetry is the point of the split.
+    // THE THIRD REFUSAL THAT IS KNOWABLE UP FRONT, and it was the one paid for
+    // with a whole build: `appimage` needs a desktop entry at its AppDir root,
+    // `kind: 'cli'` stages none by design, and both facts are configuration. It
+    // used to surface inside the packer — after `runProjectBuild` — so a CLI
+    // project asking for an AppImage built everything first and was then told its
+    // payload could never have become one. The ICON half stays in the packer,
+    // because an icon is discovered and discovery legitimately reads build output.
+    //
+    // BEFORE `assertCanPack` AND NOT AFTER IT, which is an ordering between two
+    // refusals rather than a detail. `assertCanPack` says "not on THIS machine" and
+    // is answered by installing something; this one says "not for THIS PROJECT",
+    // which installing appimagetool would not fix. Reporting the machine first
+    // sends a CLI author to a GitHub release for a tool that was never going to
+    // help them — measured, because the e2e below asserted the message it wanted
+    // and only ever ran on a host that had the tool.
+    if (!args.stage)
+        assertKindCanPack(formats, resolveShipKind(ship, flatpak));
     if (!args.stage)
         for (const format of formats)
             assertCanPack(format);
@@ -398,7 +416,14 @@ async function assemble(args) {
     // `.deb`/`.rpm` postinst compiles the SYSTEM directory at install time
     // (`utils/ship/scripts.ts`), where our schemas merge with every other
     // package's — shipping a prebuilt cache there would be a file the install step
-    // overwrites. So the compile is conditional on the layout and nothing else.
+    // overwrites, and one `rpm -e` takes away with it.
+    //
+    // WHICH IS WHY THIS CONDITION IS ABOUT THE STAGE AND NOT ABOUT INSTALL STEPS,
+    // a distinction that used to be invisible because the two agreed. They stopped
+    // agreeing when the AppImage landed: it takes the Linux layout and has no
+    // install step at all. It does not get its cache from here — a Linux stage
+    // serves three formats and only one of them wants one — it compiles its own
+    // into the AppDir, on its own pack path (`packOne`, `case 'appimage'`).
     const planned = [
         ...planStage(settings, stageInputs),
         ...(layout.os === 'linux'
@@ -949,6 +974,80 @@ async function packOne(input) {
                 verbose: input.verbose,
             });
             break;
+        case 'appimage': {
+            // FROM THE PAYLOAD, like every other container here and NOT from the
+            // stage directory, so the three properties `writePayload` guarantees
+            // hold: the modes are the plan's, the stage's own sidecar stays out
+            // because it was never payload, and `--target appimage` alone works
+            // without another row having run first.
+            //
+            // The host requirement list is derived HERE rather than inside the
+            // packer, because it is the same pair of inputs `deriveDepends` takes
+            // one branch up — `input.namespaces` from the stage manifest and
+            // `facts.bundledTypelibs` from the payload. Two derivations would be
+            // two answers to "what does this artifact need from the machine", from
+            // one build, in two files.
+            const hostRequirements = appImageHostRequirements({
+                app: settings.app,
+                minGjsVersion: settings.minGjsVersion,
+                minNodeVersion: settings.minNodeVersion,
+                namespaces: input.namespaces,
+                bundledTypelibs: facts.bundledTypelibs,
+            });
+            const appDir = appDirFor(outRoot);
+            // THE ONE FILE THIS FORMAT ADDS TO THE PAYLOAD, and the reason it is
+            // added HERE and not where every other layout's is (the stage, above).
+            // An AppImage has no install step; the Linux layout it inherits assumes
+            // one, because until this format existed every Linux artifact had a
+            // `postinst`. The compile cannot move up into the stage: the Linux stage
+            // is shared with the `.deb` and the `.rpm`, whose `share/glib-2.0/schemas`
+            // is `/usr/share/glib-2.0/schemas` — the SYSTEM directory — and a cache
+            // staged there is this app's 700 bytes installed over every other
+            // package's schemas, then taken away with `rpm -e`.
+            //
+            // FROM THE PAYLOAD, like the host requirements two lines up and for the
+            // same reason: `--from-stage` has the schema BYTES and not the project
+            // directory they were read from.
+            const schemaCache = await compileSchemasForPayload({
+                payload,
+                workDir: join(outRoot, 'appimage-schemas'),
+            });
+            const tree = appDirPayload(settings, payload, hostRequirements, schemaCache);
+            // ONE `writePayload` FOR THE WHOLE AppDir, prefix and root files
+            // together, because that call WIPES: two of them would leave the
+            // previous run's `<appId>.desktop` and icon at a root the second call
+            // never cleaned, and appimagetool packs an AppDir with two desktop
+            // files without complaining about either.
+            writePayload(appDir, tree, '');
+            // AND THEN THE TIMES, which are the single difference between two packs
+            // of one build (measured, sha256): mksquashfs stores per-file mtimes
+            // and `writePayload`'s own `mkdir`/`writeFileSync` leave the wall clock.
+            stampAppDirTimes(appDir, tree, mtime);
+            // PRINTED, not logged at `--verbose`. ADR 0024 § 9's objection to this
+            // format is that "runs anywhere" is a claim the file cannot keep, and
+            // the answer is that the file says what it does not carry — to the
+            // person building it, every time, and not only in a document.
+            console.log(`${LOG} the AppImage takes these from the host: ${hostRequirements.join(', ')}`);
+            // AND WHAT IT EMBEDS, on the same terms and for the same reason. The
+            // requirement list above says what the file does NOT carry; this says
+            // where the one thing it DOES carry that this tree did not write came
+            // from. With a pin that is a checkable claim (no network, and two packs
+            // of one build embed identical bytes); without one appimagetool fetches
+            // from a rolling tag, which still works and must still be said —
+            // ADR 0024 § A26.1. Unconditional, never behind `--verbose`: the person
+            // who can pin a runtime is the one reading a pack log.
+            const runtimeFile = findPinnedRuntime(archLabel);
+            console.log(`${LOG} ${appImageRuntimeNotice(archLabel, runtimeFile)}`);
+            await buildAppImage({
+                appDir,
+                target,
+                archLabel,
+                runtimeFile,
+                workDir: dirname(appDir),
+                verbose: input.verbose,
+            });
+            break;
+        }
         case 'macos-app':
         case 'windows-dir':
             // ONE STATEMENT FOR TWO ROWS, folded because the code really is

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

@@ -0,0 +1,372 @@
+import type { PayloadEntry } from './payload.js';
+import type { PackSettings } from './types.js';
+/** The tool this packer execs. One spelling, read by this module AND by the format row. */
+export declare const APPIMAGE_TOOL = "appimagetool";
+/**
+ * The environment variable the AppImage runtime reads to extract instead of mount.
+ *
+ * Named rather than inlined because two different programs read it for two
+ * different reasons — `appimagetool` when this packer runs it, and the artifact
+ * when a user runs that — and the spec asserts on the pair.
+ */
+export declare const EXTRACT_AND_RUN = "APPIMAGE_EXTRACT_AND_RUN";
+/**
+ * Where a PINNED AppImage runtime is looked for, and the variable that moves it.
+ *
+ * THE RUNTIME IS THE HALF OF THE ARTIFACT THIS TREE DOES NOT WRITE, and until it
+ * was pinned nothing pinned it: appimagetool fetches `runtime-<arch>` from
+ * `type2-runtime`'s ROLLING `continuous` tag on every pack (module header), so
+ * the ~940 KB of ELF a user downloads and executes arrived with no digest behind
+ * it, while `.docker/ci-fedora.Dockerfile` carefully pinned the tool that fetched
+ * it. Measured, and not a theoretical drift: `continuous`'s `runtime-x86_64` and
+ * the dated `20251108` release's differ in content at the same 944632 bytes.
+ *
+ * A DIRECTORY AND AN ENVIRONMENT VARIABLE, rather than a download this packer
+ * performs, because that is ADR 0024 § A25's rule applied one level down — a
+ * pack step that fetches is a release step that fails when GitHub does. The CI
+ * image puts a digest-checked file here; a workstation either does the same or
+ * takes the announced path below. Arch-named, `runtime-<arch>`, which is
+ * type2-runtime's own asset name, so pinning one is a copy and not a rename.
+ */
+export declare const APPIMAGE_RUNTIME_DIR_ENV = "GJSIFY_APPIMAGE_RUNTIME_DIR";
+/** The default home for {@link APPIMAGE_RUNTIME_DIR_ENV}, which the CI image fills. */
+export declare const APPIMAGE_RUNTIME_DIR = "/usr/local/share/gjsify/appimage-runtime";
+/**
+ * The AppDir's thumbnail, and the reason this packer writes it rather than
+ * letting appimagetool do it.
+ *
+ * MEASURED, AS A REPRODUCIBILITY DEFECT, and it is the kind only a byte
+ * comparison finds: appimagetool creates `.DirIcon` as a SYMLINK to the root icon
+ * when the AppDir does not already have one, and it does that AFTER
+ * {@link stampAppDirTimes} has run — so the link carries the wall clock, the
+ * AppDir root directory's own mtime moves with it, and mksquashfs stores both.
+ * Two `gjsify ship --target appimage` runs over ONE build then differ in sha256
+ * while every listing, mode, size and byte of content is identical (measured: 965
+ * differing bytes, the first inside `.digest_md5`, because the embedded digest
+ * follows the filesystem it covers). Four packs over the SAME AppDir are
+ * byte-identical, which is what makes this a mutation of the tree rather than a
+ * nondeterministic packer.
+ *
+ * A REGULAR FILE and not a symlink, for `dmg.ts`'s reason: `writePayload` writes
+ * regular files and nothing else — a property `tests/e2e/ship` asserts, and one
+ * `actions/upload-artifact` would silently dereference anyway. squashfs
+ * deduplicates the second copy, so it costs an inode and no data.
+ */
+export declare const DIR_ICON_NAME = ".DirIcon";
+/**
+ * The one directory the staged prefix goes under inside the AppDir.
+ *
+ * Exported because `stampAppDirTimes` and the e2e reader both address paths
+ * through it, and a second `'usr'` literal is the kind that stays right until
+ * somebody changes the first one.
+ */
+export declare const APPDIR_PREFIX_DIR = "usr";
+/**
+ * Where the AppDir is assembled, under the run's own output root.
+ *
+ * A directory of its own, never `out/`, for the reason `dmgVolumeDir` gives one
+ * format over: appimagetool packs everything it finds in the AppDir, so a stray
+ * sibling would ride into the image and the reader that would catch it is the
+ * same listing comparison that would then have to be relaxed to allow it.
+ */
+export declare function appDirFor(outRoot: string): string;
+/**
+ * What the AppImage does NOT carry, derived from the payload rather than authored.
+ *
+ * THE HONEST HALF OF ADR 0024 § 9, as data. The same scan that gives the `.deb`
+ * its `Depends: gir1.2-gtk-4.0` gives this its `Gtk-4.0`, so the two artifacts
+ * built from one payload cannot disagree about what the host has to provide —
+ * and the AppImage's version is distro-NEUTRAL on purpose, because there is no
+ * distribution to name package names in. A user reading `Gtk-4.0` can find it on
+ * any system; a user reading `gir1.2-gtk-4.0` on Fedora cannot.
+ *
+ * The interpreter is first and always present: it is the requirement that is
+ * never satisfied by accident, and the one {@link renderAppRun} can check from a
+ * shell script.
+ */
+export declare function appImageHostRequirements(input: {
+    app: PackSettings['app'];
+    minGjsVersion?: string;
+    minNodeVersion?: string;
+    namespaces: readonly string[];
+    bundledTypelibs?: readonly string[];
+}): string[];
+/**
+ * The version this payload's interpreter must be at least, as the project declared it.
+ *
+ * ONE DECISION, TWO READERS, which is why it is a function and not two ternaries:
+ * {@link appImageHostRequirements} PRINTS this floor and {@link renderAppRun}
+ * CHECKS it, and an artifact whose message names 1.86 while its script compares
+ * against something else is worse than one that does neither.
+ */
+export declare function interpreterFloor(input: {
+    app: PackSettings['app'];
+    minGjsVersion?: string;
+    minNodeVersion?: string;
+}): string;
+/**
+ * The `AppRun` the AppImage runtime execs, and the one check it makes first.
+ *
+ * IT EXECS THE STAGED LAUNCHER AND ADDS NOTHING TO IT. `bin/<name>` already
+ * resolves its own prefix — `readlink -f "$0"` then two `dirname`s
+ * (`renderPrefixLauncher`) — and exports `XDG_DATA_DIRS`, `GI_TYPELIB_PATH`,
+ * `GJSIFY_LOCALE_DIR` and `GJSIFY_FONT_DIR` relative to it. Inside a mounted
+ * image that resolves to `/tmp/.mount_xxxx/usr`, measured, so every locator the
+ * `.deb` sets up is already correct here. Re-exporting any of them from AppRun
+ * would be a second answer to a question the payload answers, and the copy that
+ * drifts is the one nothing tests: `tests/e2e/ship-layout` compares the staged
+ * trees, not this script.
+ *
+ * THAT CLAIM WAS RE-MEASURED AGAINST THE ARTIFACT and it holds — which is worth
+ * writing down, because when Learn6502 0.8.0's AppImage died on `GSettings schema
+ * … not found` this script was the obvious suspect and adding
+ * `GSETTINGS_SCHEMA_DIR` here was the obvious fix. It would have changed nothing.
+ * Measured on the real 0.8.0 image, by compiling `gschemas.compiled` into the
+ * extracted AppDir and touching NO environment variable anywhere: the application
+ * started. The launcher's `XDG_DATA_DIRS` was already pointing GSettings at the
+ * right directory; the directory had no cache in it. An extra export would have
+ * been a second name for a path that was already correct, and it would have
+ * "fixed" the bug by sitting next to the change that did.
+ *
+ * WHAT IT DOES ADD is the refusal ADR 0024 § 9 asks for. An AppImage whose
+ * interpreter is missing exits with the loader's own message — `gjs: not found`
+ * from a shell, or nothing at all when a desktop launches it — and the user
+ * concludes the download is broken. `command -v` costs one fork and turns that
+ * into a sentence naming the runtime, this file's promise and the escape hatch.
+ * The typelib half is deliberately NOT checked here: girepository's search path
+ * is not a shell-visible thing, and GJS's own "Typelib file for namespace 'Gtk'
+ * not found" is already precise. Listing them in the refusal is what this file
+ * can honestly do — checking them would be a probe that guesses.
+ *
+ * AND THE FLOOR IS CHECKED, FAIL-OPEN, which is the one design decision in this
+ * script. `command -v gjs` alone accepted GJS 1.70 while the message beside it
+ * said `gjs (>= 1.86)` — a floor the `.deb` enforces through `Depends:` and this
+ * artifact merely printed, so the failure it exists to prevent came back one
+ * import later. The check costs the same fork `command -v` already cost.
+ *
+ * FAIL-OPEN IS THE POINT AND NOT A HEDGE. A version comparison in `/bin/sh` that
+ * gets it wrong REFUSES A WORKING SYSTEM, which is strictly worse than not
+ * checking: the user cannot argue with an artifact. So the refusal fires only on
+ * two integers that were actually parsed out of the interpreter's own
+ * `--version`, and every other outcome — no output, a spelling this `sed` does
+ * not match, a distro build that prints something else entirely — RUNS THE
+ * APPLICATION. `gjs --version` prints `gjs 1.88.1` and `node --version` prints
+ * `v24.19.0`; both reduce to a major and a minor, and a floor with no minor
+ * (`24`) compares as `24.0`.
+ *
+ * EXIT 126 AND NOT 127 for the too-old case, because the shell's own vocabulary
+ * already separates them: 127 is "not found", 126 is "found and cannot be run".
+ * A wrapper script that wants to tell the two apart can, and the message says
+ * which it is either way.
+ */
+export declare function renderAppRun(settings: PackSettings, hostRequirements: readonly string[]): string;
+/**
+ * The icon appimagetool needs at the AppDir root, chosen from the payload.
+ *
+ * AN APPIMAGE NEEDS TWO FILES THE PREFIX ALREADY HAS, AT A PLACE IT DOES NOT:
+ * appimagetool refuses an AppDir without a `.desktop` at its root, and the file
+ * named by that entry's `Icon=` must sit beside it. `plan.ts` stages both — the
+ * entry at `share/applications/<appId>.desktop` and every icon renamed to
+ * `<appId>` under `share/icons/hicolor/…` — so this function is a SELECTION over
+ * the payload rather than anything new in the stage, which is ADR 0024 § 2's
+ * "one payload, a handful of layouts" holding for a fourth format.
+ *
+ * LARGEST RASTER WINS, and the size comes from the hicolor directory rather than
+ * from reading the file: `share/icons/hicolor/256x256/apps/<id>.png` says 256 in
+ * its path, and a PNG header read would be a decoder this packer would then own.
+ * `scalable` sorts above every raster size as the SVG fallback and `symbolic` is
+ * excluded outright — its staged name is `<appId>-symbolic`, which is not what
+ * the desktop entry's `Icon=` says, so shipping it as the root icon installs an
+ * icon nothing ever looks up (`plan.ts` documents the same rule for the theme).
+ */
+/**
+ * The pinned runtime for this architecture, or `undefined` when none is staged here.
+ *
+ * PURE APART FROM ONE INJECTED PROBE, so both answers are testable on a host that
+ * has neither — the split {@link appImageToolArgs} draws for the flags. `exists`
+ * is a parameter for exactly that reason and defaults to the real one.
+ */
+export declare function findPinnedRuntime(archLabel: string, env?: NodeJS.ProcessEnv, exists?: (path: string) => boolean): string | undefined;
+/**
+ * What this pack is about to do about the runtime, as ONE sentence `ship` prints
+ * unconditionally.
+ *
+ * DECLARE RATHER THAN IMPLY — {@link appImageHostRequirements}'s rule, applied to
+ * the other half of the artifact. With a pin the claim is checkable: no network,
+ * and two packs of one build agree because the embedded bytes are fixed. Without
+ * one the pack still works and still produces a correct-architecture container —
+ * so refusing would cost the three architectures nothing here pins, for a
+ * property they never had. What it must not do is happen silently: an AppImage
+ * built this way carries bytes from a rolling tag that nothing in this tree can
+ * name, and the person who can fix that is the one reading this line.
+ */
+export declare function appImageRuntimeNotice(archLabel: string, runtimeFile: string | undefined): string;
+export declare function selectAppDirIcon(payload: readonly PayloadEntry[], appId: string): PayloadEntry | undefined;
+/**
+ * Refuse a payload that cannot become an AppImage, naming the missing half.
+ *
+ * BEFORE appimagetool RATHER THAN THROUGH IT, and the two refusals it replaces
+ * are why: a `kind: 'cli'` project stages no desktop entry at all, and
+ * appimagetool answers that with `Desktop file not found, aborting` — true, and
+ * about a file the author never wrote and cannot find. Same for the icon. Both
+ * failures are decided by the project's OWN configuration (`gjsify.ship.kind`,
+ * `gjsify.ship.icon`), so the message that helps is the one that names the key.
+ *
+ * Separate from `assertToolsInstalled` and `assertHostCanFinish` for the reason
+ * those two are separate from each other (ADR 0024 § A3): three failures, three
+ * different fixes — a different machine, a package, or a line in package.json.
+ */
+export declare function assertAppImageIsPackable(payload: readonly PayloadEntry[], settings: PackSettings, schemaCache?: PayloadEntry): void;
+/**
+ * The whole AppDir as one payload: the prefix under `usr/`, plus the compiled
+ * schema cache, plus the three files at its root.
+ *
+ * THE SCHEMA CACHE IS AN ARGUMENT AND NOT A COMPILE, so this function stays pure
+ * and so the one impure step in the AppDir has exactly one home (`packOne`). It
+ * is prefix-relative on the way in — `share/glib-2.0/schemas/gschemas.compiled`,
+ * the same shape every other entry has — and gets the `usr/` prefix from the same
+ * map below, because a second spelling of that prefix is the thing this packer
+ * spent a comment explaining it must not have. `undefined` is legal and means the
+ * payload has no schemas at all; a payload that HAS them and no cache is refused
+ * by {@link assertAppImageIsPackable}, not silently packed.
+ *
+ * PURE, AND ONE LIST RATHER THAN A WRITER, which is the shape `msi.ts` and
+ * `dmg.ts` already have — `packOne` owns the single `writePayload` call for every
+ * format, and the packer module owns what goes in it. Two calls here would be two
+ * wipes, and the second would not clean the first: an AppDir root still holding
+ * the PREVIOUS app id's `.desktop` and icon is an AppDir appimagetool packs
+ * without complaint, because it looks for *a* desktop file and finds two.
+ *
+ * `usr/` AND NOT THE APPDIR ROOT — that prefix is the whole layout difference
+ * between this format and the `.deb` beside it, and it is why
+ * `FormatDescriptor.prefix` can stay `/usr`. The staged launcher walks up two
+ * directories from its own resolved path, so under a mount it computes
+ * `<mount>/usr` and every locator it exports is already right. A payload written
+ * at the root would make it compute the MOUNTPOINT, and the app would look for
+ * its schemas one directory too high — at exit 0, until the first
+ * `Gio.Settings.new()`.
+ */
+export declare function appDirPayload(settings: PackSettings, payload: readonly PayloadEntry[], hostRequirements: readonly string[], schemaCache?: PayloadEntry): PayloadEntry[];
+/**
+ * The argument vector, as data.
+ *
+ * Pure, so every flag is unit-testable on a host with no `appimagetool` — the
+ * same split `hdiutilCreateArgs` draws for `hdiutil` and `renderShipFlatpakManifest`
+ * for `flatpak-builder`: what the tool is TOLD is checkable everywhere, what the
+ * tool DOES needs the tool.
+ *
+ * `--no-appstream` IS A DECISION AND NOT A DEFAULT. appimagetool otherwise runs
+ * `appstreamcli validate-tree` over the AppDir, which would make the pack succeed
+ * or fail depending on whether a package unrelated to packaging is installed —
+ * green on a workstation with `appstream` and red in a container without it, over
+ * a payload that is byte-identical. A validator whose presence changes the
+ * outcome is the class this repository calls green-CI-that-checked-nothing, read
+ * backwards. The MetaInfo is still validated, by the tool that exists for it:
+ * `gjsify flatpak check --appstream` runs `appstreamcli validate --strict` on
+ * demand, where a missing `appstreamcli` is the point of the command rather than
+ * a surprise inside another one.
+ *
+ * `--comp zstd` is pinned for `hdiutilCreateArgs`' reason one format over: it is
+ * 1.9.1's current default, and a default is a thing that changes. The reader the
+ * oracle leg runs is `unsquashfs` from squashfs-tools, which needs its zstd
+ * support compiled in — measured present on Fedora 44 (4.6.1) and on
+ * ubuntu-24.04's 4.6.1. Pinning means the day appimagetool switches to something
+ * newer, this file changes and the reader is considered, instead of the reader
+ * silently losing the ability to open what we ship.
+ *
+ * `--runtime-file` IS PASSED WHEN THERE IS ONE TO PASS, and its absence is the
+ * only thing in this vector that is not a decision — see
+ * {@link findPinnedRuntime}. With it, the pack embeds bytes this tree pinned and
+ * needs no network (measured: the whole pack succeeds with the network blocked,
+ * and two packs are byte-identical). Without it appimagetool fetches its own, the
+ * pack is announced as doing so, and the artifact is still correct — just built
+ * from something nothing here can name.
+ */
+export declare function appImageToolArgs(input: {
+    appDir: string;
+    target: string;
+    runtimeFile?: string;
+}): string[];
+/**
+ * The environment appimagetool is run with — both entries REQUIRED, neither a hint.
+ *
+ * `ARCH` because appimagetool derives the architecture from the ELF binaries it
+ * finds in the AppDir, and a `--app gjs` payload has none: it is JavaScript and a
+ * `/bin/sh` launcher. Without this the tool exits 1 with "Could not determine
+ * architecture automatically", on a payload that is perfectly fine. The value is
+ * the format row's `archName`, so the architecture inside the file and the one in
+ * its name are one decision.
+ *
+ * `APPIMAGE_EXTRACT_AND_RUN` because appimagetool is itself an AppImage and
+ * mounts itself through libfuse to start — see the module header. Set
+ * unconditionally: a native `appimagetool` build ignores it, so there is no host
+ * for which this is wrong and no flag for a CI author to discover.
+ */
+export declare function appImageToolEnv(archLabel: string): Record<string, string>;
+/**
+ * What a non-zero `appimagetool` exit is, in the order a host actually hits them.
+ *
+ * PURE, so the one message a user reads at the worst moment is assertable without
+ * a container — the same split {@link appImageToolArgs} draws. It was inline until
+ * the list was found to be missing its FIRST entry, which is the shape a message
+ * that nothing reads back tends to have.
+ *
+ * THE FIRST CAUSE DEPENDS ON WHETHER A RUNTIME WAS PINNED, and getting that
+ * wrong is what this function existed to fix in the first place: with no pin the
+ * download is where an offline host fails (measured — exit 1, no file, `Failed to
+ * download runtime file`), and with one there is no download to fail, so naming
+ * it would send a reader with a working network to debug their firewall. So the
+ * pinned branch names the pinned FILE instead, which is the thing that is new in
+ * that configuration and the only one this tree chose.
+ */
+export declare function appImageToolFailureMessage(exit: string, runtimeFile?: string): string;
+export interface AppImagePackInput {
+    appDir: string;
+    target: string;
+    archLabel: string;
+    verbose: boolean;
+    /** The pinned runtime to embed, or `undefined` to let appimagetool fetch one. */
+    runtimeFile?: string;
+    /** Working root, so the log can name the directory that became the image. */
+    workDir: string;
+}
+/**
+ * Run appimagetool over the AppDir.
+ *
+ * THE FAILURE PATHS ARE THE POINT. A packer that execs a foreign tool inherits
+ * that tool's silence, and appimagetool's container failures were MEASURED on
+ * `fedora:44` rather than guessed. Without `APPIMAGE_EXTRACT_AND_RUN=1` it exits
+ * **127** pointing at the AppImageKit FUSE wiki — which is why
+ * {@link appImageToolEnv} sets that variable and this branch should never see it.
+ * Without `file(1)` it exits **1** with "file command is missing but required",
+ * EVEN with `ARCH` set, which is the failure a minimal image really hits and
+ * which says nothing about packaging. And without a network it exits **1** having
+ * written nothing, because the runtime is fetched rather than embedded — see the
+ * module header. {@link appImageToolFailureMessage} names all four.
+ *
+ * AND THE ARTIFACT IS VERIFIED TO EXIST. appimagetool prints "Success" and a
+ * request to submit to AppImageHub; it does not guarantee the destination was
+ * written, and a packer whose contract is "there is a file at `target`" must not
+ * hand `statSync` a path that is not there and report the ENOENT as a `ship` bug.
+ */
+export declare function buildAppImage(input: AppImagePackInput): Promise<void>;
+/**
+ * Every path an AppDir holding this payload has, files and the directories above
+ * them, deepest LAST.
+ *
+ * Pure and separate from the stamping, so the "which paths" half is testable with
+ * no filesystem at all — and so the answer comes from the payload rather than
+ * from a directory walk, which would read back whatever the writer happened to
+ * leave rather than what it was told to write.
+ */
+export declare function appDirPaths(payload: readonly PayloadEntry[]): string[];
+/**
+ * Give every path in the AppDir one mtime.
+ *
+ * See the module header: this is the single difference between two packs of one
+ * build, measured by sha256. `utimesSync` on a directory is legal and is where a
+ * squashfs directory inode's time comes from, so directories are stamped as well
+ * — `writePayload`'s `mkdir` gives them the wall clock and nothing else would
+ * take it away.
+ */
+export declare function stampAppDirTimes(appDir: string, payload: readonly PayloadEntry[], mtime: number): void;