@gjsify/cli 0.43.0 → 0.45.0

package/lib/utils/ship/signing.js

@@ -0,0 +1,317 @@
+// Signing the payload, and submitting the artifact for notarisation
+// (ADR 0024 § A12–§ A17).
+//
+// FOUR PROPERTIES, each one a decision the ADR settles and this file implements:
+//
+//  1. `--sign` takes an IDENTITY, not a certificate (§ A12). `codesign` is handed
+//     a STRING and looks the private key up itself; `-` is the reserved value for
+//     ad-hoc, and this tree already writes `codesign --force --sign -` in five
+//     places. So there is no `--certificate`, no `--p12` and no `--password`
+//     anywhere on this surface — getting a key into a keychain is the signing
+//     HOST's job (§ A14), and nothing here can leak a secret it is never given.
+//  2. An absent identity SKIPS, loudly, at exit 0 (§ A13). Unsigned is the
+//     default path and a legitimate deliverable; what § 5 refuses is the other
+//     direction — claiming a signature that was not made.
+//  3. Signing is a payload MUTATION, not a wrapper (§ A4). Under hardened
+//     runtime a Developer-ID-signed main executable will not load ad-hoc-signed
+//     dylibs, and all 106 Mach-O images in the shipped darwin GTK closure carry
+//     an ad-hoc `LC_CODE_SIGNATURE` already (they must — `install_name_tool`
+//     invalidates the original during relocation). So the darwin leg re-signs
+//     every image, and the result is new BYTES for the packer rather than a
+//     container around the old ones.
+//  4. THE ORDER IS STRUCTURAL, not conventional (§ A17). `readStage` compares
+//     each file's SIZE against `.gjsify-ship-stage.json`, and a size is no more
+//     re-sign-proof than a digest. BOTH halves are measured and they agree:
+//     append one byte to a staged file and `readStage` refuses with "… is 6
+//     bytes in the stage and 5 in its manifest"; and an ad-hoc `codesign
+//     --force --sign -` over one staged image took it from 34 816 to 34 848
+//     bytes (+32) on macos-latest/arm64. {@link signPayload} therefore TAKES what `readStage`
+//     returned and RETURNS what the packer consumes: the signed bytes cannot
+//     exist before the validation, because they are computed from its output,
+//     and the arriving stage is never written to at all.
+//
+// WHAT THIS DELIBERATELY DOES NOT DO, each with its reason:
+//
+//  * It does not seal the `<App>.app` BUNDLE. `codesign` on a bundle writes
+//    `Contents/_CodeSignature/CodeResources` and — for a main executable that is
+//    a shell script, which every layout's launcher is — stores that script's own
+//    signature in an extended attribute (Apple's documented behaviour, not
+//    measured here). What IS measured here is our side of it: the payload round
+//    trip is `readStage` → bytes + mode → `writePayload`, and it carries no
+//    extended attributes at all, so a bundle seal made now would not survive into
+//    the `.zip` beside the `.app`. The images the dynamic loader validates are
+//    the ones signed, which is what § A4's argument is about.
+//  * It passes no `--options runtime`, no `--entitlements` and no `--timestamp`.
+//    § A16 leaves library validation vs. hardened runtime explicitly unmeasured,
+//    and a secure timestamp needs a real Developer ID plus network. Adding any of
+//    them would be code no run in this repository has ever executed.
+//  * It does not staple, and the reason is NOT that stapling is unevidenced.
+//    Measured here on `refs/node` at the pinned `0618e9f0`, against the ADR's own
+//    control of 16 files for `codesign`: `stapler` returns 4 files, of which
+//    `tools/osx-notarize.sh:58` is real code — `xcrun stapler staple
+//    "node-$pkgid.pkg"`, three lines past where § A15 stopped quoting; the other
+//    three are changelog entries. What is NOT measured is whether it accepts
+//    OUR container: the reference staples a `.pkg`, and the only file-shaped
+//    darwin artifact this command produces is a `.zip`. Adding a call that may
+//    refuse the one artifact it would run on is code no run in this repository
+//    has exercised, deciding something it cannot justify. Recorded in
+//    `status/open-todos.md` instead.
+import { readFileSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { isOnPath } from '../check-system-deps.js';
+import { describeExit, spawnToCompletion } from '../spawn.js';
+import { listFilesRecursive } from './discover.js';
+import { classifyBinary } from './payload.js';
+import { writePayload } from './stage-writer.js';
+/**
+ * The signers, keyed by the LAYOUT they sign — never by the host they run on.
+ *
+ * Linux is deliberately absent rather than present-and-empty. A `.deb` and an
+ * `.rpm` carry no per-file signature: the artifact is signed as a whole, by the
+ * repository that serves it (`debsigs`, `rpmsign`), with a key that belongs to
+ * that repository and not to this build. A row here would make `--sign` on Linux
+ * look like it did something.
+ */
+export const SIGNERS = {
+    darwin: {
+        layoutOs: 'darwin',
+        tool: 'codesign',
+        // The tool is Apple's and ships with the Command Line Tools. There is no
+        // Linux `codesign`, so unlike every other step of the darwin leg this one
+        // really is host-bound — which is why it lives on the FINISH phase and
+        // `gjsify ship darwin --stage` needs none of it.
+        signOn: ['darwin'],
+        installHint: 'install the Xcode Command Line Tools (`xcode-select --install`) on a macOS host',
+        signs: 'macho',
+        // `--force` because every image in the shipped closure is ALREADY signed
+        // ad-hoc (§ A4: 106 of 106) — `install_name_tool` invalidates the original
+        // during relocation and the relocator re-signs. Without it `codesign`
+        // refuses a file that already carries a signature.
+        args: (identity, file) => ['--force', '--sign', identity, file],
+        configKey: 'gjsify.ship.sign.darwin.identity',
+        gap: 'the images are signed; the `.app` bundle itself is not sealed and no entitlements are ' +
+            'granted (ADR 0024 § A16 leaves library validation unmeasured)',
+    },
+    win32: {
+        layoutOs: 'win32',
+        tool: 'signtool',
+        signOn: ['win32'],
+        installHint: 'install the Windows SDK (signtool.exe ships in its `bin/<version>/x64` directory)',
+        signs: 'pe',
+        // `/n` takes a SUBJECT NAME and looks the certificate up in a store, which
+        // is the same shape as `codesign --sign <identity>` and the reason § A12's
+        // interface is one flag for both OSes. `/fd sha256` names the file digest;
+        // Authenticode's default is SHA-1, which no current Windows accepts.
+        //
+        // ⚠️ UNVERIFIED. Nothing in this repository has ever run `signtool`: it
+        // needs a certificate, there is no ad-hoc mode on Windows, and § A5
+        // records that SmartScreen only WARNS until per-file-hash reputation
+        // accrues — signed or not. The argv is unit-tested, the skip and the
+        // refusals are e2e-tested, and the invocation itself has no proof.
+        args: (identity, file) => ['sign', '/n', identity, '/fd', 'sha256', file],
+        configKey: 'gjsify.ship.sign.win32.identity',
+        gap: 'no timestamp countersignature is requested, so the signature expires with the certificate ' +
+            '(UNVERIFIED: no run in this repository has ever invoked signtool)',
+    },
+};
+/**
+ * Resolve the identity for this run, or say why there is none.
+ *
+ * `flag` beats `config` and neither is a yargs `default:` — the uniform
+ * precedence `resolveShipSettings` documents. `config` is `undefined` on the
+ * `--from-stage` path and that is not an omission: § A14 amends § A1 to *a
+ * format declares where it can be packed; the RUN declares what it can sign
+ * with*, and the finishing host has no project to read a default out of.
+ */
+export function resolveSignPlan(input) {
+    const signer = SIGNERS[input.layoutOs];
+    if (signer === undefined) {
+        if (input.flag !== undefined) {
+            throw new Error(`gjsify ship: --sign has nothing to sign in the ${input.layoutOs} layout. A .deb and an .rpm ` +
+                'carry no per-file signature — the artifact is signed as a whole by the repository that ' +
+                "serves it (`debsigs`, `rpmsign`), with that repository's key and not with a build-time " +
+                'identity. Drop --sign, or assemble the darwin or windows layout.');
+        }
+        return { kind: 'unsupported' };
+    }
+    const configured = input.config?.[input.layoutOs]?.identity;
+    const [identity, source] = input.flag !== undefined ? [input.flag, 'flag'] : [configured, 'config'];
+    // The reference's `[ -z "$SIGN" ]` — an EMPTY identity is a skip and not an
+    // error, and the skip is printed rather than silent so a pipeline that
+    // captures the artifact list still shows it (§ A13). Ours names the step it
+    // skipped, which the reference's own copy-pasted message does not.
+    if (identity === undefined || identity === '') {
+        const said = identity === ''
+            ? `an empty identity was ${source === 'flag' ? 'passed to --sign' : `set in \`${signer.configKey}\``}`
+            : 'no identity was given';
+        return {
+            kind: 'skip',
+            message: `${said} — skipping ${signer.tool}. An unsigned artifact is the default path and a ` +
+                `legitimate deliverable (ADR 0024 § A13). Pass \`--sign <identity>\` or set ` +
+                `\`${signer.configKey}\` to sign; \`--sign -\` signs ad-hoc and needs no developer identity.`,
+        };
+    }
+    return { kind: 'sign', identity, signer, source };
+}
+/**
+ * Refuse a signing run this host cannot make, and say which half is missing.
+ *
+ * Two checks and not one, for the same reason `assertCanPack` splits them: the
+ * wrong OS needs another machine, an absent tool needs a package. Both are
+ * knowable before anything is packed.
+ */
+export function assertHostCanSign(signer) {
+    const host = process.platform;
+    if (!signer.signOn.includes(host)) {
+        throw new Error(`gjsify ship: signing the ${signer.layoutOs} layout needs ${signer.tool}, which runs on ` +
+            `${signer.signOn.join(', ')} and this host is ${host}. Assembly is not host-bound — ` +
+            '`gjsify ship <os> --stage` here, then `gjsify ship --from-stage <dir> --sign <identity>` ' +
+            'on a host that has both the tool and the identity (ADR 0024 § A1, § A14).');
+    }
+    if (!isOnPath(signer.tool)) {
+        throw new Error(`gjsify ship: --sign was given and \`${signer.tool}\` is not on PATH, so nothing can make the ` +
+            `signature — ${signer.installHint}. Dropping --sign produces an unsigned artifact, which is ` +
+            'a legitimate output (ADR 0024 § A13); silently producing one while --sign was asked for is not.');
+    }
+}
+/**
+ * Re-sign every signable image in the payload, and hand back the new bytes.
+ *
+ * The signature is made on FILES because that is the only interface `codesign`
+ * and `signtool` have, so the payload is materialised into `workDir`, signed
+ * there, and read back. `workDir` is a scratch directory rather than the stage:
+ * writing into an arriving stage would make the next `--from-stage` run of the
+ * same tree fail `readStage`'s size comparison (measured — see the header), and
+ * `writeStage`'s wipe would delete the payload it was about to pack.
+ *
+ * THE FILE SET MAY NOT CHANGE, and that is asserted rather than assumed. Both
+ * tools rewrite an image in place, so a payload that gained or lost a path here
+ * means something else ran — a bundle seal writing `_CodeSignature/`, say, whose
+ * files would then be dropped on the way back into the payload without anyone
+ * noticing.
+ */
+export async function signPayload(input) {
+    const { payload, signer, workDir } = input;
+    writePayload(workDir, payload, '');
+    const signable = payload.filter((entry) => classifyBinary(entry.data) === signer.signs);
+    if (signable.length === 0) {
+        // NOT silent, and not an error either. A `--app gjs` payload really is
+        // JavaScript and a launcher, so there is nothing for the loader to
+        // validate — but a run that asked for a signature and made none has to
+        // say so, or "signed" and "signed nothing" look identical in the log.
+        input.log(`nothing in this payload is a ${signer.signs === 'macho' ? 'Mach-O' : 'PE'} image, so ` +
+            `${signer.tool} signed 0 file(s). The artifact carries no signature.`);
+        return [...payload];
+    }
+    for (const entry of signable) {
+        const file = join(workDir, entry.path.split('/').join(sep));
+        const args = signer.args(input.identity, file);
+        if (input.verbose)
+            input.log(`${signer.tool} ${args.join(' ')}`);
+        const result = await spawnToCompletion(signer.tool, args, {
+            completion: 'return',
+            cwd: workDir,
+            stdio: 'inherit',
+            notFound: () => new Error(`gjsify ship: \`${signer.tool}\` is not on PATH — ${signer.installHint}.`),
+        });
+        if (result.code !== 0) {
+            throw new Error(`gjsify ship: ${signer.tool} failed on ${entry.path} with ${describeExit(result)}. ` +
+                'Nothing is packed from a payload whose signature failed: an artifact that is half ' +
+                'signed installs and is refused at first launch, which is worse than not shipping.');
+        }
+    }
+    const arrived = new Set(listFilesRecursive(workDir));
+    const planned = new Set(payload.map((entry) => entry.path));
+    const added = [...arrived].filter((path) => !planned.has(path));
+    const removed = [...planned].filter((path) => !arrived.has(path));
+    if (added.length > 0 || removed.length > 0) {
+        throw new Error(`gjsify ship: ${signer.tool} changed the payload's file set — ` +
+            `${added.length} added (${added.slice(0, 3).join(', ') || '—'}), ` +
+            `${removed.length} removed (${removed.slice(0, 3).join(', ') || '—'}). ` +
+            'Signing is a mutation of the files that are already in the payload (ADR 0024 § A4); a ' +
+            'file that appeared here would be packed with no mode from the plan, and one that ' +
+            'vanished would be packed as absent.');
+    }
+    input.log(`${signer.tool} signed ${signable.length} of ${payload.length} payload file(s) as ` +
+        `${input.identity === '-' ? 'ad-hoc (`-`)' : `\`${input.identity}\``} — ${signer.gap}.`);
+    // Modes come from the PLAN, exactly as `readStage` insists: the signer
+    // rewrites bytes and this re-read must not turn a 0755 launcher into
+    // whatever the scratch directory's umask produced.
+    return payload.map((entry) => ({
+        path: entry.path,
+        mode: entry.mode,
+        data: new Uint8Array(readFileSync(join(workDir, entry.path.split('/').join(sep)))),
+    }));
+}
+export const NOTARIES = {
+    darwin: {
+        layoutOs: 'darwin',
+        tool: 'xcrun',
+        notarizeOn: ['darwin'],
+        installHint: 'install the Xcode Command Line Tools (`xcode-select --install`) on a macOS host',
+        args: (credential, artifact) => ['notarytool', 'submit', '--keychain-profile', credential, '--wait', artifact],
+    },
+};
+/**
+ * Resolve the notarisation credential, or say why there is none.
+ *
+ * Deliberately NOT defaultable from the project. An identity is a name a machine
+ * may hold for years and is worth writing into a repository; a notarisation
+ * credential is a per-run account credential, and a config key for it is an
+ * invitation to commit one.
+ */
+export function resolveNotaryPlan(input) {
+    const notary = NOTARIES[input.layoutOs];
+    if (notary === undefined) {
+        if (input.flag !== undefined) {
+            throw new Error(`gjsify ship: --notarize has no meaning in the ${input.layoutOs} layout. Notarisation is ` +
+                "Apple's pre-clearance of a signed artifact and nothing else asks for it — Windows " +
+                'SmartScreen accrues reputation per file hash instead (ADR 0024 § A5).');
+        }
+        return { kind: 'unsupported' };
+    }
+    if (input.flag === undefined || input.flag === '') {
+        return {
+            kind: 'skip',
+            message: `no notarisation credential was given — skipping ${notary.tool} notarytool. Pass ` +
+                '`--notarize <keychain-profile>`, naming a profile a prior `notarytool store-credentials` ' +
+                "put in this host's keychain.",
+        };
+    }
+    if (input.sign.kind !== 'sign') {
+        throw new Error('gjsify ship: --notarize was given without an identity to sign with. Notarisation is a check ' +
+            'ON a signature, so submitting an unsigned artifact has nothing to clear. Pass ' +
+            '`--sign <identity>` as well, or drop --notarize.');
+    }
+    return { kind: 'notarize', credential: input.flag, notary };
+}
+/**
+ * Submit one written artifact for notarisation.
+ *
+ * ⚠️ UNVERIFIED END TO END. Everything up to the `spawnToCompletion` is covered
+ * — the argv by `signing.spec.ts`, the guard and both refusals by
+ * `tests/e2e/ship-signing` — and the invocation itself has never run: it needs
+ * an Apple Developer account, and § A17's whole point is that M6's proof does
+ * not. Whoever first runs this on a real credential should record what it did
+ * beside § A15, which is where the question was left open.
+ */
+export async function notarizeArtifact(input) {
+    const { notary, credential } = input.plan;
+    const host = process.platform;
+    if (!notary.notarizeOn.includes(host)) {
+        throw new Error(`gjsify ship: notarising the ${notary.layoutOs} layout needs ${notary.tool}, which runs on ` +
+            `${notary.notarizeOn.join(', ')} and this host is ${host}.`);
+    }
+    const args = notary.args(credential, input.artifact);
+    if (input.verbose)
+        input.log(`${notary.tool} ${args.join(' ')}`);
+    const result = await spawnToCompletion(notary.tool, args, {
+        completion: 'return',
+        stdio: 'inherit',
+        notFound: () => new Error(`gjsify ship: \`${notary.tool}\` is not on PATH — ${notary.installHint}.`),
+    });
+    if (result.code !== 0) {
+        throw new Error(`gjsify ship: ${notary.tool} notarytool failed with ${describeExit(result)}.`);
+    }
+    input.log(`${notary.tool} notarytool accepted ${input.artifact}. The artifact is NOT stapled.`);
+}

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

@@ -1,4 +1,4 @@
-import type { FormatDescriptor, FormatId, PackSettings, ShipSettings, StagedFile, StagedMode } from './types.js';
+import type { FormatDescriptor, FormatId, HostOs, PackSettings, ShipSettings, StagedFile, StagedMode } from './types.js';
 /** The one file a stage carries that is not payload. Lives at the stage ROOT. */
 export declare const STAGE_MANIFEST_FILE = ".gjsify-ship-stage.json";
 /**
@@ -10,21 +10,55 @@ export declare const STAGE_MANIFEST_FILE = ".gjsify-ship-stage.json";
  * Bump it whenever a field's MEANING changes, not when one is added that an
  * older reader would simply ignore; a reader that ignores a field it does not
  * know is exactly how a mode plan silently loses an entry.
- */
-export declare const STAGE_SCHEMA_VERSION = 1;
-/**
- * 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.
+ * 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.
+ *
+ * 3 added `settings.minNodeVersion` and 4 added `settings.app`. Same case as 2
+ * for the same reason: an older reader ignoring `app` does not skip a field, it
+ * has no concept of an interpreter choice at all, so it seeds `gjs >= …` for a
+ * stage whose launcher — already rendered, already in the tree it is packing —
+ * execs `node`. The package then declares one interpreter and runs another.
+ *
+ * Stated as a consequence and not as an incident, because it never happened:
+ * `app` and the launcher landed together. An earlier version of this comment
+ * claimed the incident anyway, which is worth leaving on the record — a rule
+ * with an invented reason gets "simplified" back out the first time somebody
+ * notices the reason is not real.
+ *
+ * WHY TWO BUMPS IN ONE CHANGE, when neither was ever released. Because 3 and 4
+ * are DIFFERENT SHAPES and 3 briefly existed: the intermediate commit wrote
+ * `schema: 3` with no `app`. Folding `app` into 3 would have made this reader
+ * meet that stage and fail on `settings.app must be "gjs" or "node", got
+ * undefined` — fail-closed, but naming a field instead of the one thing the
+ * reader can do about it. At 4 the schema check above catches it first and says
+ * "re-run the `--stage` phase with this gjsify", which is the whole reason this
+ * constant's header is an argument for bumping whenever a reader could mis-read.
+ *
+ * 5 added `settings.name`, and it was decided against the criterion above rather
+ * than reflexively — #1354 M2a changed two things and only one of them warrants a
+ * bump:
+ *
+ *  - NOT the two new format ids. `formats[]` and `overlay`'s keys carry new
+ *    VALUES in fields whose meaning is unchanged, and `readStageManifest` already
+ *    refuses a `formats[i]` it does not know BY NAME. An older gjsify meeting a
+ *    macOS stage therefore fails closed with a message about the format, which is
+ *    the right message. Adding a member to a validated enum is the case this
+ *    header says not to bump for.
+ *  - YES `settings.name`. It is REQUIRED, so this reader meeting a schema-4 stage
+ *    would fail on `settings.name must be a string` — naming a field instead of
+ *    the one thing the reader can do about it. That is the same shape the 3-to-4
+ *    paragraph describes, and at 5 the schema check above fires first and says
+ *    "re-run the `--stage` phase with this gjsify".
  */
-export declare const STAGE_LAYOUT_OS = "linux";
+export declare const STAGE_SCHEMA_VERSION = 5;
 /** What this stage was assembled FOR, in the repo-wide `${process.platform}-${process.arch}` spelling. */
 export interface StageTarget {
-    os: string;
+    /** The layout the stage carries, in the `process.platform` spelling — `win32`, never `windows`. */
+    os: HostOs;
     arch: string;
 }
 /** One staged path, its planned mode, and the size it had when the stage was written. */
@@ -72,7 +106,10 @@ export interface StageManifestInput {
  * `extraFiles` and `licenseFile` — seven absolute paths from the assembling
  * host — into a file whose whole purpose is to be read somewhere else. The
  * explicit list is also what makes adding a field a decision: see the comment
- * on {@link PackSettings} for what belongs on each side.
+ * on {@link PackSettings} for what belongs on each side. `appId` and `flatpak`
+ * were that decision for the Flatpak target, and the `--from-stage` e2e is
+ * where an omission would have shown: it deletes the project, so a field the
+ * packer needs and the manifest lacks has nowhere to be read from.
  */
 export declare function toPackSettings(settings: ShipSettings): PackSettings;
 /** Absolute path of a stage's manifest. */

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

@@ -38,6 +38,7 @@ 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';
+import { layoutForOs, LAYOUTS, LAYOUT_NAMES } from './layout.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';
 /**
@@ -49,18 +50,51 @@ export const STAGE_MANIFEST_FILE = '.gjsify-ship-stage.json';
  * Bump it whenever a field's MEANING changes, not when one is added that an
  * older reader would simply ignore; a reader that ignores a field it does not
  * know is exactly how a mode plan silently loses an entry.
- */
-export const STAGE_SCHEMA_VERSION = 1;
-/**
- * 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.
+ * 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.
+ *
+ * 3 added `settings.minNodeVersion` and 4 added `settings.app`. Same case as 2
+ * for the same reason: an older reader ignoring `app` does not skip a field, it
+ * has no concept of an interpreter choice at all, so it seeds `gjs >= …` for a
+ * stage whose launcher — already rendered, already in the tree it is packing —
+ * execs `node`. The package then declares one interpreter and runs another.
+ *
+ * Stated as a consequence and not as an incident, because it never happened:
+ * `app` and the launcher landed together. An earlier version of this comment
+ * claimed the incident anyway, which is worth leaving on the record — a rule
+ * with an invented reason gets "simplified" back out the first time somebody
+ * notices the reason is not real.
+ *
+ * WHY TWO BUMPS IN ONE CHANGE, when neither was ever released. Because 3 and 4
+ * are DIFFERENT SHAPES and 3 briefly existed: the intermediate commit wrote
+ * `schema: 3` with no `app`. Folding `app` into 3 would have made this reader
+ * meet that stage and fail on `settings.app must be "gjs" or "node", got
+ * undefined` — fail-closed, but naming a field instead of the one thing the
+ * reader can do about it. At 4 the schema check above catches it first and says
+ * "re-run the `--stage` phase with this gjsify", which is the whole reason this
+ * constant's header is an argument for bumping whenever a reader could mis-read.
+ *
+ * 5 added `settings.name`, and it was decided against the criterion above rather
+ * than reflexively — #1354 M2a changed two things and only one of them warrants a
+ * bump:
+ *
+ *  - NOT the two new format ids. `formats[]` and `overlay`'s keys carry new
+ *    VALUES in fields whose meaning is unchanged, and `readStageManifest` already
+ *    refuses a `formats[i]` it does not know BY NAME. An older gjsify meeting a
+ *    macOS stage therefore fails closed with a message about the format, which is
+ *    the right message. Adding a member to a validated enum is the case this
+ *    header says not to bump for.
+ *  - YES `settings.name`. It is REQUIRED, so this reader meeting a schema-4 stage
+ *    would fail on `settings.name must be a string` — naming a field instead of
+ *    the one thing the reader can do about it. That is the same shape the 3-to-4
+ *    paragraph describes, and at 5 the schema check above fires first and says
+ *    "re-run the `--stage` phase with this gjsify".
  */
-export const STAGE_LAYOUT_OS = 'linux';
+export const STAGE_SCHEMA_VERSION = 5;
 /**
  * The half of {@link ShipSettings} that crosses the host boundary.
  *
@@ -69,11 +103,16 @@ export const STAGE_LAYOUT_OS = 'linux';
  * `extraFiles` and `licenseFile` — seven absolute paths from the assembling
  * host — into a file whose whole purpose is to be read somewhere else. The
  * explicit list is also what makes adding a field a decision: see the comment
- * on {@link PackSettings} for what belongs on each side.
+ * on {@link PackSettings} for what belongs on each side. `appId` and `flatpak`
+ * were that decision for the Flatpak target, and the `--from-stage` e2e is
+ * where an omission would have shown: it deletes the project, so a field the
+ * packer needs and the manifest lacks has nowhere to be read from.
  */
 export function toPackSettings(settings) {
     return {
         binaryName: settings.binaryName,
+        appId: settings.appId,
+        name: settings.name,
         version: settings.version,
         release: settings.release,
         maintainer: settings.maintainer,
@@ -85,7 +124,10 @@ export function toPackSettings(settings) {
         group: settings.group,
         extraDepends: settings.extraDepends,
         typelibPackages: settings.typelibPackages,
+        app: settings.app,
         minGjsVersion: settings.minGjsVersion,
+        minNodeVersion: settings.minNodeVersion,
+        flatpak: settings.flatpak,
     };
 }
 /** Absolute path of a stage's manifest. */
@@ -121,7 +163,13 @@ export function writeStageManifest(input) {
     const manifest = {
         schema: STAGE_SCHEMA_VERSION,
         tool: { name: '@gjsify/cli', version: cliVersion() },
-        target: { os: STAGE_LAYOUT_OS, arch: input.settings.arch },
+        // The POSITIONAL's value, not a constant. It used to be the literal
+        // `'linux'`, correct while the planner produced exactly one layout and
+        // wrong the moment it produced three — and wrong SILENTLY, because a
+        // darwin stage labelled `linux-arm64` passes every structural check in
+        // `readStageManifest` and would be accepted by `--expect-target
+        // linux-arm64` on a leg that wanted the Linux one.
+        target: { os: input.settings.layoutOs, arch: input.settings.arch },
         formats: input.formats.map((format) => format.id),
         mtime: input.mtime,
         namespaces: [...input.namespaces],
@@ -192,7 +240,16 @@ export function readStageManifest(stageDir) {
             version: expectString(tool.version, at('tool.version')),
         },
         target: {
-            os: expectString(target.os, at('target.os')),
+            // `layoutForOs`, which takes the `process.platform` spelling and NO
+            // alias. `resolveLayout` — the positional's resolver — also accepts
+            // `windows`, and routing this field through it would mean a manifest
+            // literally saying `"windows"` was accepted and then COMPARED as
+            // `win32`: two files with different bytes in the one field
+            // `--expect-target` exists to compare would both match it, on a wire
+            // format whose entire job is to catch a job that downloaded the wrong
+            // artifact. Refused here rather than reaching the layout lookup as a
+            // lie, and named the way every other field in this function is.
+            os: expectLayoutOs(expectString(target.os, at('target.os')), at('target.os')),
             arch: expectString(target.arch, at('target.arch')),
         },
         formats: expectArray(data.formats, at('formats')).map((entry, index) => {
@@ -247,6 +304,26 @@ export function readStageManifest(stageDir) {
     }
     return manifest;
 }
+/**
+ * `target.os`, resolved to a layout, in the one spelling this field may carry.
+ *
+ * The catch REPLACES the message rather than swallowing it: `layoutForOs` speaks
+ * about a token, and this is a named field in a file that arrived from another
+ * host, so the fix is different and so is the sentence. Every other field in
+ * `readStageManifest` names its own location the same way.
+ */
+function expectLayoutOs(value, where) {
+    try {
+        return layoutForOs(value).os;
+    }
+    catch {
+        const known = LAYOUT_NAMES.map((name) => LAYOUTS[name].os).join(', ');
+        throw new Error(`gjsify ship: ${where} is "${value}", which is not a layout this gjsify can pack. It carries ` +
+            `the \`process.platform\` spelling and only that — ${known}, so \`win32\` and never ` +
+            "`windows`. A stage holds exactly one OS's layout and every path in it has that OS's shape, " +
+            'so there is nothing to pack here. Re-run the `--stage` phase.');
+    }
+}
 /** The overlay for one format, in the shape `writeStage` takes. */
 export function overlayFiles(manifest, format) {
     return (manifest.overlay[format] ?? []).map((file) => ({
@@ -307,7 +384,11 @@ 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 ` +
+    throw new Error(
+    // `no format at all` and not an empty join: a stage CAN record zero formats
+    // (`gjsify.ship.targets` filtered to a layout none of them wrap), and the
+    // join printed that as nothing — "assembled for , and --target names …".
+    `gjsify ship: this stage was assembled for ${manifest.formats.length === 0 ? 'no format at all' : 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 ' +
@@ -355,6 +436,8 @@ function readPackSettings(data, at) {
     const typelibPackages = record(data.typelibPackages, field('typelibPackages'));
     return {
         binaryName: expectString(data.binaryName, field('binaryName')),
+        appId: expectString(data.appId, field('appId')),
+        name: expectString(data.name, field('name')),
         version: expectString(data.version, field('version')),
         release: expectString(data.release, field('release')),
         maintainer: expectString(data.maintainer, field('maintainer')),
@@ -378,7 +461,34 @@ function readPackSettings(data, at) {
                 },
             ];
         })),
+        app: expectApp(data.app, field('app')),
         minGjsVersion: expectString(data.minGjsVersion, field('minGjsVersion')),
+        minNodeVersion: expectString(data.minNodeVersion, field('minNodeVersion')),
+        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) {
@@ -393,6 +503,19 @@ function expectArray(value, at) {
     }
     return value;
 }
+/**
+ * The interpreter field, checked against the two values that exist.
+ *
+ * Not `expectString`: this one decides which interpreter the package DEPENDS on,
+ * so an unknown value must stop the pack rather than flow into a `Depends:` line
+ * as itself. The only way to reach it is a stage from a gjsify that knows a third
+ * target, which the schema check above already refuses — this is the second wall.
+ */
+function expectApp(value, at) {
+    if (value === 'gjs' || value === 'node')
+        return value;
+    throw new Error(`gjsify ship: ${at} must be "gjs" or "node", got ${JSON.stringify(value)}.`);
+}
 function expectString(value, at) {
     if (typeof value !== 'string') {
         throw new Error(`gjsify ship: ${at} must be a string. Re-run the \`--stage\` phase.`);