@gjsify/cli 0.42.0 → 0.44.0

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

@@ -0,0 +1,445 @@
+// `.gjsify-ship-stage.json` — what one `gjsify ship --stage` hands the
+// `gjsify ship --from-stage` that finishes it (ADR 0024 § A2).
+//
+// A CLOSURE, not a settings dump. The packing host has the staged tree and
+// nothing else: no project directory, no `package.json`, no built bundle, no
+// `gjsify.ship` config. Everything the packers still need has to be in here,
+// and everything that is a BUILD-HOST PATH must not be — serialised verbatim,
+// `bundlePath` and friends name files that do not exist where they are read.
+//
+// The measurement that decided the contents: each of these omissions fails
+// SILENTLY, at exit 0, with an artifact that installs.
+//
+//   * no `staged` — modes come from the plan (see `stage-writer.ts`), so the
+//     launcher packs 0644 and the installed `bin/<name>` is not executable.
+//   * no `overlay` — the `.deb` ships no `/usr/share/doc/<pkg>/copyright`,
+//     which Debian Policy § 12.5 requires and lintian errors on, and the
+//     `.rpm` ships no `/usr/share/licenses/<pkg>/LICENSE`.
+//   * no `namespaces` — they are scanned from the BUILD TREE's bundle, so a
+//     packing host that re-derived nothing would emit `Depends:` without
+//     `gir1.2-gtk-4.0` and `gir1.2-adw-1`: the package installs on a machine
+//     with no GTK and dies at the first import. That is the exact failure
+//     ADR 0024 § 6 exists to prevent, moved one host to the left.
+//   * no `mtime` — an artifact upload does not carry mtimes, so re-stat'ing
+//     the stage stamps every header with the download time and two hosts
+//     packing the same stage produce different bytes.
+//
+// What is deliberately NOT carried, so the next reader does not add it back:
+//   * per-file digests. ADR 0024 § A4 measured that the darwin finish leg has
+//     to re-sign all 106 Mach-O images inside the stage, at which point a
+//     sha256 set either refuses the artifact it exists to produce or is
+//     relaxed to exempt 106 files and stops checking anything. A per-file SIZE
+//     survives that and still catches the truncated transfer, so that is what
+//     `staged[].bytes` is.
+//   * anything derivable from the payload — `hasIcons`, `hasSchemas`, the
+//     bundled typelibs. `readPayloadFacts` answers all three from the tree
+//     that is right there.
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { cliVersion } from '../publish-headers.js';
+import { FORMAT_IDS } from './formats.js';
+/** The one file a stage carries that is not payload. Lives at the stage ROOT. */
+export const STAGE_MANIFEST_FILE = '.gjsify-ship-stage.json';
+/**
+ * The schema this CLI writes and the only one it reads.
+ *
+ * A stage is a short-lived intermediate between two jobs of ONE run, not an
+ * archive, so there is no migration path in either direction and both
+ * mismatches are refused rather than guessed at — see {@link readStageManifest}.
+ * 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 = 2;
+/**
+ * The OS whose layout `planStage` produces.
+ *
+ * A constant rather than a measurement, because it is a property of the PLAN
+ * (`bin/`, `lib/<name>/`, `share/…` is the Linux/XDG layout), not of the host
+ * that ran it — assembling is cross-platform (ADR 0024 § A1). When
+ * `gjsify ship darwin --stage` lands this becomes the positional's value, and
+ * this constant is where the compiler will point.
+ */
+export const STAGE_LAYOUT_OS = 'linux';
+/**
+ * The half of {@link ShipSettings} that crosses the host boundary.
+ *
+ * Written out field by field rather than spread: a spread would carry
+ * `projectDir`, `bundlePath`, `bundleDir`, `iconFiles`, `schemaFiles`,
+ * `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. `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,
+        summary: settings.summary,
+        description: settings.description,
+        license: settings.license,
+        ...(settings.homepage === undefined ? {} : { homepage: settings.homepage }),
+        section: settings.section,
+        group: settings.group,
+        extraDepends: settings.extraDepends,
+        typelibPackages: settings.typelibPackages,
+        minGjsVersion: settings.minGjsVersion,
+        flatpak: settings.flatpak,
+    };
+}
+/** Absolute path of a stage's manifest. */
+export function stageManifestPath(stageDir) {
+    return join(stageDir, STAGE_MANIFEST_FILE);
+}
+/** `linux-x64`. One spelling repo-wide (root AGENTS.md § Runtime & platform model). */
+export function formatTarget(target) {
+    return `${target.os}-${target.arch}`;
+}
+/**
+ * Write the manifest at the stage root, AFTER the tree itself.
+ *
+ * `bytes` is stat'ed off the written tree rather than taken from the plan: the
+ * plan holds a source path or a string, and what the packing host will compare
+ * against is what actually landed on disk here.
+ */
+export function writeStageManifest(input) {
+    const overlay = {};
+    for (const format of input.formats) {
+        overlay[format.id] = (input.overlay.get(format.id) ?? []).map((file) => {
+            if (file.source.kind !== 'text') {
+                // Every overlay entry `planOverlay` produces today is rendered text. A file
+                // reference would be a build-host path, and putting one in here is how the
+                // manifest would start naming files the packing host cannot open.
+                throw new Error(`gjsify ship: internal error — the ${format.id} overlay entry ${file.path} is a file ` +
+                    'reference, and a stage manifest may only carry rendered text. Render it in ' +
+                    '`planOverlay` instead.');
+            }
+            return { path: file.path, mode: file.mode, text: file.source.text };
+        });
+    }
+    const manifest = {
+        schema: STAGE_SCHEMA_VERSION,
+        tool: { name: '@gjsify/cli', version: cliVersion() },
+        target: { os: STAGE_LAYOUT_OS, arch: input.settings.arch },
+        formats: input.formats.map((format) => format.id),
+        mtime: input.mtime,
+        namespaces: [...input.namespaces],
+        settings: toPackSettings(input.settings),
+        staged: input.staged.map((file) => ({
+            path: file.path,
+            mode: file.mode,
+            bytes: statSync(join(input.stageDir, file.path.split('/').join(sep))).size,
+        })),
+        overlay,
+    };
+    writeFileSync(stageManifestPath(input.stageDir), `${JSON.stringify(manifest, null, 2)}\n`);
+    return manifest;
+}
+/**
+ * Read and validate a stage's manifest.
+ *
+ * Every field is checked, because this file is the only thing standing between
+ * "a directory someone pointed us at" and a signed-looking `.deb`. A missing
+ * `staged` entry would reach `readStage` as a mode nobody planned; a `mode` that
+ * arrived as a string would reach `chmod` as `NaN`.
+ */
+export function readStageManifest(stageDir) {
+    const path = stageManifestPath(stageDir);
+    if (!existsSync(path)) {
+        throw new Error(`gjsify ship: ${stageDir} has no ${STAGE_MANIFEST_FILE}, so it is not a stage this command can ` +
+            'pack. A stage is produced by `gjsify ship --stage`, which writes that file at the stage root ' +
+            "beside the payload. If you pointed --from-stage at a project's `ship/` directory, point it at " +
+            '`ship/stage/` instead.');
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch (error) {
+        throw new Error(`gjsify ship: ${path} is not readable JSON (${error.message}). ` +
+            'Re-run the `--stage` phase; a truncated manifest means the stage transfer was truncated too.');
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error(`gjsify ship: ${path} is not a JSON object. Re-run the \`--stage\` phase.`);
+    }
+    const data = raw;
+    const schema = data.schema;
+    if (typeof schema !== 'number' || !Number.isInteger(schema)) {
+        throw new Error(`gjsify ship: ${path} has no integer \`schema\` field, so it was not written by \`gjsify ship ` +
+            '--stage`. Re-run the `--stage` phase.');
+    }
+    if (schema > STAGE_SCHEMA_VERSION) {
+        throw new Error(`gjsify ship: ${path} declares schema ${schema} and this gjsify understands ` +
+            `${STAGE_SCHEMA_VERSION}. The stage was assembled by a newer gjsify: upgrade this one ` +
+            '(`gjsify self-update`), or re-run the `--stage` phase with this version. A manifest from the ' +
+            'future is refused rather than partially read, because an unknown field could be the one that ' +
+            "decides a file's mode.");
+    }
+    if (schema < STAGE_SCHEMA_VERSION) {
+        throw new Error(`gjsify ship: ${path} declares schema ${schema} and this gjsify understands ` +
+            `${STAGE_SCHEMA_VERSION}. Re-run the \`--stage\` phase with this gjsify. A stage is a ` +
+            'short-lived intermediate between two jobs of one run, not an archive, so no migration is ' +
+            'kept for it.');
+    }
+    const at = (field) => `${path} → ${field}`;
+    const tool = record(data.tool, at('tool'));
+    const target = record(data.target, at('target'));
+    const manifest = {
+        schema,
+        tool: {
+            name: expectString(tool.name, at('tool.name')),
+            version: expectString(tool.version, at('tool.version')),
+        },
+        target: {
+            os: expectString(target.os, at('target.os')),
+            arch: expectString(target.arch, at('target.arch')),
+        },
+        formats: expectArray(data.formats, at('formats')).map((entry, index) => {
+            const id = expectString(entry, at(`formats[${index}]`));
+            if (!FORMAT_IDS.includes(id)) {
+                throw new Error(`gjsify ship: ${at(`formats[${index}]`)} is "${id}", which this gjsify does not know. ` +
+                    `Known formats: ${FORMAT_IDS.join(', ')}.`);
+            }
+            return id;
+        }),
+        mtime: expectInteger(data.mtime, at('mtime')),
+        namespaces: expectArray(data.namespaces, at('namespaces')).map((entry, index) => expectString(entry, at(`namespaces[${index}]`))),
+        settings: readPackSettings(record(data.settings, at('settings')), at('settings')),
+        staged: expectArray(data.staged, at('staged')).map((entry, index) => {
+            const file = record(entry, at(`staged[${index}]`));
+            return {
+                path: expectString(file.path, at(`staged[${index}].path`)),
+                mode: expectInteger(file.mode, at(`staged[${index}].mode`)),
+                bytes: expectInteger(file.bytes, at(`staged[${index}].bytes`)),
+            };
+        }),
+        overlay: {},
+    };
+    // `readStage` refuses in both directions — a staged path the plan does not name,
+    // and a planned path the stage lacks — but both sides can be empty TOGETHER and
+    // agree. Measured: a directory holding only the sidecar packed into a structurally
+    // valid `ship-demo_1.2.3-1_all.deb` that `dpkg -i` installs and that contains no
+    // `bin/` and no `lib/`; the command simply does not exist afterwards.
+    if (manifest.staged.length === 0) {
+        throw new Error(`gjsify ship: ${at('staged')} is empty, so this stage describes no payload. ` +
+            'A stage always carries at least the launcher its plan named. Re-run the ' +
+            '`--stage` phase; a stage that lost its plan cannot be packed into anything ' +
+            'but an empty package.');
+    }
+    const overlay = record(data.overlay, at('overlay'));
+    for (const id of manifest.formats) {
+        // No `?? []`: `writeStageManifest` emits a key for every staged format even
+        // when the project has no LICENCE (the value is then an empty array), so a
+        // MISSING key can only mean a mutilated manifest. Defaulting it away is the
+        // `?? 0o644` bug one field over — measured: with `"overlay": {}` the finish
+        // phase exited 0 and wrote a `.deb` carrying no
+        // `/usr/share/doc/<pkg>/copyright`, which Debian Policy § 12.5 requires and
+        // lintian errors on.
+        manifest.overlay[id] = expectArray(overlay[id], at(`overlay.${id}`)).map((entry, index) => {
+            const file = record(entry, at(`overlay.${id}[${index}]`));
+            return {
+                path: expectString(file.path, at(`overlay.${id}[${index}].path`)),
+                mode: expectInteger(file.mode, at(`overlay.${id}[${index}].mode`)),
+                text: expectString(file.text, at(`overlay.${id}[${index}].text`)),
+            };
+        });
+    }
+    return manifest;
+}
+/** The overlay for one format, in the shape `writeStage` takes. */
+export function overlayFiles(manifest, format) {
+    return (manifest.overlay[format] ?? []).map((file) => ({
+        path: file.path,
+        mode: file.mode,
+        source: { kind: 'text', text: file.text },
+    }));
+}
+/**
+ * Refuse a stage that is not the one this job was told to pack.
+ *
+ * WHAT THIS IS: a matrix-leg mix-up check. It catches a finish job that
+ * downloaded the wrong artifact — the leg that forgot to route — and nothing
+ * more. It is opt-in (no flag, no check) and it compares two strings the same
+ * pipeline wrote one job apart, so treat a green run as "this is the stage I
+ * asked for", never as "this stage is correctly labelled".
+ *
+ * WHAT THIS IS NOT: the guard its precedent
+ * (`packages/node-gi/scripts/verify-bundle-manifest.mjs --expect-host-target`)
+ * provides. That script compares a bundle to `process.platform`/`process.arch`
+ * because the runner BUILT it, so the machine is the right second opinion.
+ * Here the stage arrives from another host by design, so a host comparison
+ * would refuse a legal use — measured: an `arm64`-labelled stage packs on this
+ * x64 host at exit 0 with correct bytes, because both packers are pure JS.
+ *
+ * The class that precedent guards — a label and the bytes under it disagreeing
+ * — is NOT guarded here, and `target.arch` cannot guard it: it is defaulted
+ * from `process.arch` only when `--arch` is absent, so the moment an operator
+ * says which leg they are on, `target.arch` is that operator's claim and
+ * nothing compares it to a machine or to a byte. Measured BEFORE
+ * {@link assertPayloadMatchesArch} existed: a stage carrying an x86-64 `.so`,
+ * assembled `--stage --arch arm64` and packed `--expect-target linux-arm64`,
+ * exited 0 and produced an `aarch64` rpm whose only `.so` was `e_machine=0x3e`.
+ * The same command in this tree now exits 1 and writes nothing — kept in the
+ * past tense because it is the reason the guard below it exists, not a
+ * description of what this function does.
+ *
+ * That class is guarded one layer down instead, where the oracle is free and
+ * cannot be wrong about a machine it never saw: {@link assertPayloadMatchesArch}
+ * in `payload.ts` reads ELF `e_machine` / Mach-O `cputype` out of the payload
+ * and refuses a label the bytes contradict. Payload-versus-label goes red on
+ * the mislabelled stage AND stays green on the legitimate cross-host pack;
+ * host-versus-label can only do one of the two.
+ */
+export function assertExpectedTarget(manifest, expected) {
+    if (expected === undefined)
+        return;
+    const actual = formatTarget(manifest.target);
+    if (expected !== actual) {
+        throw new Error(`gjsify ship: --expect-target ${expected} but this stage was assembled for ${actual}. ` +
+            'The stage records the target its `--arch` resolved to at stage time, so this is a stage from ' +
+            'another matrix leg: download the artifact belonging to ' +
+            `${expected}, or drop --expect-target if packing this one is what you meant.`);
+    }
+}
+/** Refuse a format the stage carries no overlay closure for. */
+export function assertFormatsStaged(manifest, formats) {
+    const missing = formats.filter((format) => !manifest.formats.includes(format.id)).map((format) => format.id);
+    if (missing.length === 0)
+        return;
+    throw new Error(`gjsify ship: this stage was assembled for ${manifest.formats.join(', ')}, and --target names ` +
+        `${missing.join(', ')}. Phase one renders each format's overlay — rpm wants the licence at ` +
+        '`share/licenses/<pkg>/LICENSE`, deb wants a machine-readable copyright at ' +
+        '`share/doc/<pkg>/copyright` — so a format the stage never saw would pack without it, and Debian ' +
+        `Policy § 12.5 makes that a broken package. Re-run \`gjsify ship --stage --target ${[
+            ...manifest.formats,
+            ...missing,
+        ].join(',')}\` on the assembling host.`);
+}
+/**
+ * The build stamp the packing host uses: the stage's, always.
+ *
+ * A `SOURCE_DATE_EPOCH` set only in the finish job would silently produce a
+ * different artifact than the same stage packed on the assembling host, which
+ * is the one property the two-phase split has to keep. It is a warning rather
+ * than a refusal because the honest fix ("set it in both jobs or in neither")
+ * is the caller's, and refusing would break a runner that exports it globally.
+ */
+export function resolveStageMtime(manifest, env = process.env) {
+    const raw = env.SOURCE_DATE_EPOCH;
+    if (raw === undefined || Number(raw) === manifest.mtime)
+        return { mtime: manifest.mtime, warnings: [] };
+    return {
+        mtime: manifest.mtime,
+        warnings: [
+            `SOURCE_DATE_EPOCH is ${raw} here and this stage was stamped ${manifest.mtime}. The stage's stamp ` +
+                'wins, because changing it would make this artifact differ from the same stage packed on the ' +
+                'assembling host. Set the same value in both jobs, or set it in neither.',
+        ],
+    };
+}
+/** One actionable line when the two phases ran different gjsify versions. */
+export function warnOnToolSkew(manifest) {
+    const running = cliVersion();
+    if (manifest.tool.version === running)
+        return [];
+    return [
+        `this stage was assembled by ${manifest.tool.name} ${manifest.tool.version} and is being packed by ` +
+            `${running}. Both phases run the same packer, so a version difference can change the artifact's ` +
+            'bytes. Pin both jobs to one gjsify version.',
+    ];
+}
+function readPackSettings(data, at) {
+    const field = (name) => `${at}.${name}`;
+    const extraDepends = record(data.extraDepends, field('extraDepends'));
+    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')),
+        summary: expectString(data.summary, field('summary')),
+        description: expectArray(data.description, field('description')).map((entry, index) => expectString(entry, field(`description[${index}]`))),
+        license: expectString(data.license, field('license')),
+        ...(data.homepage === undefined ? {} : { homepage: expectString(data.homepage, field('homepage')) }),
+        section: expectString(data.section, field('section')),
+        group: expectString(data.group, field('group')),
+        extraDepends: {
+            deb: expectArray(extraDepends.deb ?? [], field('extraDepends.deb')).map((entry, index) => expectString(entry, field(`extraDepends.deb[${index}]`))),
+            rpm: expectArray(extraDepends.rpm ?? [], field('extraDepends.rpm')).map((entry, index) => expectString(entry, field(`extraDepends.rpm[${index}]`))),
+        },
+        typelibPackages: Object.fromEntries(Object.entries(typelibPackages).map(([namespace, value]) => {
+            const row = record(value, field(`typelibPackages.${namespace}`));
+            return [
+                namespace,
+                {
+                    deb: expectString(row.deb, field(`typelibPackages.${namespace}.deb`)),
+                    rpm: expectString(row.rpm, field(`typelibPackages.${namespace}.rpm`)),
+                },
+            ];
+        })),
+        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) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`gjsify ship: ${at} must be an object. Re-run the \`--stage\` phase.`);
+    }
+    return value;
+}
+function expectArray(value, at) {
+    if (!Array.isArray(value)) {
+        throw new Error(`gjsify ship: ${at} must be an array. Re-run the \`--stage\` phase.`);
+    }
+    return value;
+}
+function expectString(value, at) {
+    if (typeof value !== 'string') {
+        throw new Error(`gjsify ship: ${at} must be a string. Re-run the \`--stage\` phase.`);
+    }
+    return value;
+}
+function expectInteger(value, at) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        throw new Error(`gjsify ship: ${at} must be a non-negative integer. Re-run the \`--stage\` phase. ` +
+            '(Modes are decimal here — JSON has no octal literal, so 0o755 is written 493.)');
+    }
+    return value;
+}

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

@@ -1,17 +1,44 @@
 import type { PayloadEntry } from './payload.js';
-import type { StagedFile } from './types.js';
+import type { StagedFile, StagePlanEntry } from './types.js';
 /**
  * Materialise a planned tree under `root`, replacing whatever was there.
  *
  * The directory is wiped first: a stale file from a previous run is otherwise
  * indistinguishable from a staged one, and would be packed.
+ *
+ * NEVER call this on a stage that ARRIVED — the wipe is unconditional, so
+ * pointing it at a downloaded stage deletes the payload it was about to pack.
+ * `gjsify ship --from-stage` writes only the format's own `overlay/` directory
+ * for that reason.
  */
 export declare function writeStage(root: string, files: readonly StagedFile[]): void;
 /**
- * Read a staged tree back as a payload.
+ * Read a staged tree back as a payload, and refuse a tree that is not the
+ * planned one.
  *
  * Modes come from the PLAN, not from `stat()`: a checked-out tree can carry
  * whatever umask the build host had, and an executable bit that survives on
  * one machine and not another is exactly the kind of difference that ships.
+ * A CI artifact is the sharpest case — `actions/upload-artifact` stores no
+ * POSIX mode at all, so a stage that made the trip has 0644 on its launcher
+ * and the plan is the only surviving record that it should be 0755.
+ *
+ * That same trip is why a disagreement is now an error in BOTH directions:
+ *
+ *  - a path in the tree the plan does not name used to be packed at `?? 0o644`.
+ *    That default is a guess about a file nobody planned; if it is a program it
+ *    installs unrunnable, and the package is otherwise perfect.
+ *  - a path in the plan the tree does not hold used to be silently absent from
+ *    the payload. `.deb` and `.rpm` both accept that happily and the result is
+ *    a package that installs and cannot start — this project's most expensive
+ *    failure class.
+ *
+ * `bytes` is compared when the plan carries it (i.e. when the plan came from a
+ * stage manifest). It catches the truncated transfer that the file-set check
+ * cannot see: a half-written upload leaves every path in place. It is a SIZE
+ * and not a digest on purpose — ADR 0024 § A4 measured that the darwin finish
+ * leg has to re-sign all 106 Mach-O images inside the stage, so a per-file
+ * sha256 would have to be relaxed to exempt them and would then be checking
+ * nothing.
  */
-export declare function readStage(roots: readonly string[], files: readonly StagedFile[]): PayloadEntry[];
+export declare function readStage(roots: readonly string[], plan: readonly StagePlanEntry[]): PayloadEntry[];

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

@@ -5,17 +5,41 @@
 // in-memory list, so "what the user inspected" and "what got packed" cannot
 // diverge. It also makes the staged tree a legitimate deliverable on its own —
 // which is what a Flatpak module's `cp -a stage/.` will consume once Flatpak
-// moves under `ship` (ADR 0024 § 8).
+// moves under `ship` (ADR 0024 § 8), and what `gjsify ship --from-stage` packs
+// on a host that has the tree and nothing else (ADR 0024 § A2).
+//
+// That second consumer is why {@link readStage} refuses rather than defaults.
+// A stage now arrives from another machine, so "the tree and the plan disagree"
+// stopped being impossible and became a transfer failure — and every way of
+// papering over it produces an artifact that installs.
 import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, sep } from 'node:path';
 import { listFilesRecursive } from './discover.js';
+import { STAGE_MANIFEST_FILE } from './stage-manifest.js';
 /**
  * Materialise a planned tree under `root`, replacing whatever was there.
  *
  * The directory is wiped first: a stale file from a previous run is otherwise
  * indistinguishable from a staged one, and would be packed.
+ *
+ * NEVER call this on a stage that ARRIVED — the wipe is unconditional, so
+ * pointing it at a downloaded stage deletes the payload it was about to pack.
+ * `gjsify ship --from-stage` writes only the format's own `overlay/` directory
+ * for that reason.
  */
 export function writeStage(root, files) {
+    for (const file of files) {
+        // The stage root carries exactly one file that is not payload, and this
+        // is its name. A planned file with the same path (reachable through
+        // `gjsify.ship.extraFiles`) would shadow the manifest: the tree would
+        // then either pack the manifest as payload or lose the closure that
+        // makes the tree packable somewhere else.
+        if (file.path === STAGE_MANIFEST_FILE) {
+            throw new Error(`gjsify ship: a payload file may not be called \`${STAGE_MANIFEST_FILE}\` — that name belongs ` +
+                'to the stage manifest, which sits at the stage root beside the payload and carries what ' +
+                'the packing host needs (ADR 0024 § A2). Rename the `gjsify.ship.extraFiles` destination.');
+        }
+    }
     rmSync(root, { recursive: true, force: true, maxRetries: 5 });
     mkdirSync(root, { recursive: true });
     for (const file of files) {
@@ -27,23 +51,66 @@ export function writeStage(root, files) {
     }
 }
 /**
- * Read a staged tree back as a payload.
+ * Read a staged tree back as a payload, and refuse a tree that is not the
+ * planned one.
  *
  * Modes come from the PLAN, not from `stat()`: a checked-out tree can carry
  * whatever umask the build host had, and an executable bit that survives on
  * one machine and not another is exactly the kind of difference that ships.
+ * A CI artifact is the sharpest case — `actions/upload-artifact` stores no
+ * POSIX mode at all, so a stage that made the trip has 0644 on its launcher
+ * and the plan is the only surviving record that it should be 0755.
+ *
+ * That same trip is why a disagreement is now an error in BOTH directions:
+ *
+ *  - a path in the tree the plan does not name used to be packed at `?? 0o644`.
+ *    That default is a guess about a file nobody planned; if it is a program it
+ *    installs unrunnable, and the package is otherwise perfect.
+ *  - a path in the plan the tree does not hold used to be silently absent from
+ *    the payload. `.deb` and `.rpm` both accept that happily and the result is
+ *    a package that installs and cannot start — this project's most expensive
+ *    failure class.
+ *
+ * `bytes` is compared when the plan carries it (i.e. when the plan came from a
+ * stage manifest). It catches the truncated transfer that the file-set check
+ * cannot see: a half-written upload leaves every path in place. It is a SIZE
+ * and not a digest on purpose — ADR 0024 § A4 measured that the darwin finish
+ * leg has to re-sign all 106 Mach-O images inside the stage, so a per-file
+ * sha256 would have to be relaxed to exempt them and would then be checking
+ * nothing.
  */
-export function readStage(roots, files) {
-    const modes = new Map(files.map((file) => [file.path, file.mode]));
+export function readStage(roots, plan) {
+    const planned = new Map(plan.map((entry) => [entry.path, entry]));
     const byPath = new Map();
     for (const root of roots) {
         for (const rel of listFilesRecursive(root)) {
-            byPath.set(rel, {
-                path: rel,
-                mode: modes.get(rel) ?? 0o644,
-                data: new Uint8Array(readFileSync(join(root, rel.split('/').join(sep)))),
-            });
+            if (rel === STAGE_MANIFEST_FILE)
+                continue;
+            const entry = planned.get(rel);
+            if (entry === undefined) {
+                throw new Error(`gjsify ship: ${join(root, rel.split('/').join(sep))} is in the stage and not in its ` +
+                    'manifest, so nothing knows what mode to give it. Every payload file takes its mode ' +
+                    'from the plan, never from the filesystem, so a file that arrived some other way would ' +
+                    'be packed 0644 — unrunnable if it is a program. Remove it, or add it through ' +
+                    '`gjsify.ship.extraFiles` and re-run the `--stage` phase.');
+            }
+            const data = new Uint8Array(readFileSync(join(root, rel.split('/').join(sep))));
+            if (entry.bytes !== undefined && entry.bytes !== data.byteLength) {
+                throw new Error(`gjsify ship: ${rel} is ${data.byteLength} bytes in the stage and ${entry.bytes} in its ` +
+                    'manifest. The stage arrived truncated or was edited after it was assembled. ' +
+                    'Re-upload it, or re-run the `--stage` phase.');
+            }
+            byPath.set(rel, { path: rel, mode: entry.mode, data });
         }
     }
+    const missing = plan.filter((entry) => !byPath.has(entry.path)).map((entry) => entry.path);
+    if (missing.length > 0) {
+        throw new Error(`gjsify ship: the stage manifest lists ${missing.length} file(s) the stage does not contain: ` +
+            `${missing.slice(0, 5).join(', ')}${missing.length > 5 ? ', …' : ''}. ` +
+            'A payload has to be complete before it is packed — both formats would pack the rest without ' +
+            'complaint and install a package that cannot start. Re-run the `--stage` phase, and check that ' +
+            'whatever moved the stage between hosts copied every file (an artifact upload that drops empty ' +
+            'files or dotfiles is the usual cause).');
+    }
     return [...byPath.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
 }