@gjsify/cli 0.44.0 → 0.45.0

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";
 /**
@@ -16,21 +16,49 @@ export declare const STAGE_MANIFEST_FILE = ".gjsify-ship-stage.json";
  * `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 declare 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.
+ * 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. */

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';
 /**
@@ -55,18 +56,45 @@ export const STAGE_MANIFEST_FILE = '.gjsify-ship-stage.json';
  * `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.
+ * 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.
  *
@@ -84,6 +112,7 @@ export function toPackSettings(settings) {
     return {
         binaryName: settings.binaryName,
         appId: settings.appId,
+        name: settings.name,
         version: settings.version,
         release: settings.release,
         maintainer: settings.maintainer,
@@ -95,7 +124,9 @@ 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,
     };
 }
@@ -132,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],
@@ -203,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) => {
@@ -258,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) => ({
@@ -318,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 ' +
@@ -367,6 +437,7 @@ function readPackSettings(data, at) {
     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')),
@@ -390,7 +461,9 @@ 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')),
     };
 }
@@ -430,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.`);

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

@@ -42,3 +42,51 @@ export declare function writeStage(root: string, files: readonly StagedFile[]):
  * nothing.
  */
 export declare function readStage(roots: readonly string[], plan: readonly StagePlanEntry[]): PayloadEntry[];
+/**
+ * Materialise a PAYLOAD — bytes already in hand — under `root`, replacing it.
+ *
+ * The twin of {@link writeStage}, and the difference is what each takes.
+ * `writeStage` writes a PLAN, whose sources are paths on the assembling host or
+ * strings; this writes what {@link readStage} handed back, which is the only shape
+ * available on a host that has the stage and nothing else.
+ *
+ * It exists for the one artifact in `FORMATS` that is a DIRECTORY: a `<App>.app`
+ * is not a container around the payload, it IS the payload plus the format's own
+ * overlay, laid out on disk. Writing it through this function rather than by
+ * copying the stage directory keeps the same two properties every other packer
+ * has — the modes come from the plan (`readStage` has already applied them, and
+ * the artifact upload that flattens them cannot reach in between), and the
+ * stage's own `.gjsify-ship-stage.json` stays out, because it was never in the
+ * payload.
+ *
+ * `root` is WIPED first, exactly as `writeStage` wipes: a `.app` left over from a
+ * previous run with a file the current payload no longer names would otherwise be
+ * signed, zipped and shipped.
+ *
+ * `stripPrefix` is what makes it the ARTIFACT rather than a directory holding
+ * one, and leaving it out produced exactly that: every staged darwin path already
+ * begins with `<App>.app/` — that is what `Layout.root` means — so writing them
+ * verbatim under an artifact called `<App>.app` gave
+ * `out/Ship Demo.app/Ship Demo.app/Contents/…`. The Finder shows the outer
+ * directory as a plain folder, so the failure is a bundle that is not one, and it
+ * is invisible to every reader that walks the tree looking for `Contents/`.
+ * Measured on the WIP this replaces; the discriminator is the depth assertion in
+ * `tests/e2e/ship-macos`.
+ *
+ * A path OUTSIDE `stripPrefix` throws rather than being written somewhere near
+ * the artifact. The alternative — pass it through — would put a file beside the
+ * bundle instead of inside it, which is the shape ADR 0024 § A4 records
+ * `codesign` refusing, and it would be silent.
+ */
+export declare function writePayload(root: string, payload: readonly PayloadEntry[], stripPrefix: string): void;
+/**
+ * Total bytes of the regular files under `root`.
+ *
+ * What `packOne` reports for a `FormatDescriptor.artifactKind: 'directory'`.
+ * `statSync` on a directory answers the directory ENTRY's size — 4096 on ext4 —
+ * so a `.app` carrying a 20 MiB bundle would be printed as "4096 bytes", which is
+ * not a rounding error but a different number. Directory entries themselves are
+ * deliberately not counted: what a user wants to know is how much payload they
+ * are about to move.
+ */
+export declare function directorySize(root: string): number;

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

@@ -12,7 +12,7 @@
 // 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 { chmodSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, sep } from 'node:path';
 import { listFilesRecursive } from './discover.js';
 import { STAGE_MANIFEST_FILE } from './stage-manifest.js';
@@ -114,3 +114,73 @@ export function readStage(roots, plan) {
     }
     return [...byPath.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
 }
+/**
+ * Materialise a PAYLOAD — bytes already in hand — under `root`, replacing it.
+ *
+ * The twin of {@link writeStage}, and the difference is what each takes.
+ * `writeStage` writes a PLAN, whose sources are paths on the assembling host or
+ * strings; this writes what {@link readStage} handed back, which is the only shape
+ * available on a host that has the stage and nothing else.
+ *
+ * It exists for the one artifact in `FORMATS` that is a DIRECTORY: a `<App>.app`
+ * is not a container around the payload, it IS the payload plus the format's own
+ * overlay, laid out on disk. Writing it through this function rather than by
+ * copying the stage directory keeps the same two properties every other packer
+ * has — the modes come from the plan (`readStage` has already applied them, and
+ * the artifact upload that flattens them cannot reach in between), and the
+ * stage's own `.gjsify-ship-stage.json` stays out, because it was never in the
+ * payload.
+ *
+ * `root` is WIPED first, exactly as `writeStage` wipes: a `.app` left over from a
+ * previous run with a file the current payload no longer names would otherwise be
+ * signed, zipped and shipped.
+ *
+ * `stripPrefix` is what makes it the ARTIFACT rather than a directory holding
+ * one, and leaving it out produced exactly that: every staged darwin path already
+ * begins with `<App>.app/` — that is what `Layout.root` means — so writing them
+ * verbatim under an artifact called `<App>.app` gave
+ * `out/Ship Demo.app/Ship Demo.app/Contents/…`. The Finder shows the outer
+ * directory as a plain folder, so the failure is a bundle that is not one, and it
+ * is invisible to every reader that walks the tree looking for `Contents/`.
+ * Measured on the WIP this replaces; the discriminator is the depth assertion in
+ * `tests/e2e/ship-macos`.
+ *
+ * A path OUTSIDE `stripPrefix` throws rather than being written somewhere near
+ * the artifact. The alternative — pass it through — would put a file beside the
+ * bundle instead of inside it, which is the shape ADR 0024 § A4 records
+ * `codesign` refusing, and it would be silent.
+ */
+export function writePayload(root, payload, stripPrefix) {
+    // `''` means "the payload is already artifact-relative"; anything else is a
+    // directory name and gets its separator here rather than at three call sites.
+    const strip = stripPrefix === '' ? '' : `${stripPrefix}/`;
+    rmSync(root, { recursive: true, force: true, maxRetries: 5 });
+    mkdirSync(root, { recursive: true });
+    for (const entry of payload) {
+        if (!entry.path.startsWith(strip)) {
+            throw new Error(`gjsify ship: ${entry.path} is outside ${stripPrefix || 'the artifact'}, which this artifact ` +
+                'IS — so there is nowhere inside it for the file to go. A payload file that escaped the ' +
+                'bundle would ship beside it, unsigned and unfound.');
+        }
+        const target = join(root, entry.path.slice(strip.length).split('/').join(sep));
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, entry.data);
+        chmodSync(target, entry.mode);
+    }
+}
+/**
+ * Total bytes of the regular files under `root`.
+ *
+ * What `packOne` reports for a `FormatDescriptor.artifactKind: 'directory'`.
+ * `statSync` on a directory answers the directory ENTRY's size — 4096 on ext4 —
+ * so a `.app` carrying a 20 MiB bundle would be printed as "4096 bytes", which is
+ * not a rounding error but a different number. Directory entries themselves are
+ * deliberately not counted: what a user wants to know is how much payload they
+ * are about to move.
+ */
+export function directorySize(root) {
+    let total = 0;
+    for (const rel of listFilesRecursive(root))
+        total += statSync(join(root, rel.split('/').join(sep))).size;
+    return total;
+}

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

@@ -36,7 +36,22 @@ export interface ShipArtifact {
     /** Size in bytes. */
     size: number;
 }
-export type FormatId = 'deb' | 'rpm' | 'flatpak';
+/**
+ * The closed vocabulary of formats.
+ *
+ * The two macOS members are spelled `macos-…` rather than `app` / `app-zip`, and
+ * the reason is collision rather than length: the bare word `app` is already
+ * taken three times over in this subsystem — the `gjsify.app` config key,
+ * `ShipSettings.app`, `PackSettings.app` — and every one of them means the
+ * INTERPRETER. A member of this union is also a directory name (`overlay/<id>/`)
+ * and a `--target` value a user types, so the ambiguity would have reached both a
+ * path and a command line.
+ *
+ * `scripts/check-ship-format-vocabulary.mjs` reads the declaration below
+ * TEXTUALLY and fails if a comment gives it a second match, which is why this one
+ * describes the union without quoting its head.
+ */
+export type FormatId = 'deb' | 'rpm' | 'flatpak' | 'macos-app' | 'macos-app-zip' | 'macos-app-dmg' | 'windows-dir' | 'windows-dir-zip' | 'msi';
 /**
  * The formats whose ARTIFACT carries a distro dependency list.
  *
@@ -57,6 +72,23 @@ export type FormatId = 'deb' | 'rpm' | 'flatpak';
 export type DistroFormatId = Extract<FormatId, 'deb' | 'rpm'>;
 /** An operating system in the repo-wide `process.platform` spelling (root AGENTS.md § Runtime & platform model). */
 export type HostOs = 'linux' | 'darwin' | 'win32';
+/**
+ * Commands a packer EXECS — a flat LIST when every host runs the same ones, and
+ * a per-OS MAP when the backend is host-SELECTED.
+ *
+ * The map arrived with the `.msi` and nothing else needs it, which is exactly why
+ * it is a union rather than a map everywhere: five of the eight rows exec one tool
+ * or none, and spelling `{ linux: [], darwin: [], win32: [] }` on each of them
+ * would make five rows say three times over what one row has to say once.
+ *
+ * The `.msi` cannot use the flat form and be honest. It is produced by `wixl` on
+ * Linux and by WiX v3 on Windows out of ONE authored `.wxs` (ADR 0024 § A6), so a
+ * flat list is wrong in both directions: the union of the two demands `wixl` of a
+ * Windows host that will never run it, and either half alone silently claims the
+ * other OS needs nothing. {@link requiredToolsOn} is the one resolver, and
+ * `assertToolsInstalled` takes the host it resolves for.
+ */
+export type RequiredTools = readonly string[] | Readonly<Partial<Record<HostOs, readonly string[]>>>;
 /**
  * Where a format can be FINISHED, and who can read the result back (ADR 0024 § A3).
  *
@@ -74,7 +106,7 @@ export interface HostRequirement {
     /** OSes whose tooling can finish this format. `'any'` = pure JS, under GJS, offline. */
     finishOn: 'any' | readonly HostOs[];
     /** Commands the packer EXECS. Empty iff this tree writes the format itself. */
-    requiredTools: readonly string[];
+    requiredTools: RequiredTools;
     /**
      * How to install {@link requiredTools}, in this format's own words.
      *
@@ -83,8 +115,13 @@ export interface HostRequirement {
      * `assertToolsInstalled`, which is correct for exactly one format and would
      * have told the first `.dmg` or `.msi` user to install flatpak — from the
      * same branchless dispatch this whole table exists to keep branchless.
-     * Required whenever `requiredTools` is non-empty; `flatpak.spec.ts` holds
-     * that, the same way it holds `selfReading`.
+     * Required whenever `requiredTools` is non-empty on ANY host; `flatpak.spec.ts`
+     * holds that, the same way it holds `selfReading`.
+     *
+     * ONE string even for a host-selected backend, and that is not a shortcut: the
+     * refusal already names the tool that is missing, so a hint covering both routes
+     * ("Fedora: … / Windows: …") answers the reader's question without a second
+     * per-OS field to keep in step with the first.
      */
     installHint?: string;
     oracle: {
@@ -110,6 +147,22 @@ export interface HostRequirement {
  */
 export interface FormatDescriptor {
     id: FormatId;
+    /**
+     * The OS whose LAYOUT this format wraps.
+     *
+     * Not `host.finishOn`, and the two must not be collapsed: `finishOn` says
+     * where the container can be PRODUCED, this says which staged tree it is a
+     * container FOR. A `.dmg` is `finishOn: ['darwin']` and `layoutOs: 'darwin'`,
+     * which makes them look like one field — but the `.app` zip beside it is
+     * `finishOn: 'any'` with the same `layoutOs`, and that is the pair that
+     * proves they are different questions.
+     *
+     * This is what gives `defaultFormatIds` its second criterion. Without it, a
+     * `.app` and a Windows program directory — both `finishOn: 'any'` — would
+     * make a bare `gjsify ship` on Linux emit five artifacts, three of which are
+     * for operating systems the caller did not ask about.
+     */
+    layoutOs: HostOs;
     /** Install prefix the format's contents hang under. */
     prefix: string;
     /** Where this format can be packed, what it execs, and who reads it back. */
@@ -119,6 +172,46 @@ export interface FormatDescriptor {
      * dependencies are not a package list at all — see {@link DistroFormatId}.
      */
     depends: DistroFormatId | null;
+    /**
+     * The interpreters this format's runtime can actually provide at RUN time.
+     *
+     * A list and not a boolean, and on the descriptor rather than in a branch,
+     * because the answer is a property of the format's runtime and nothing else
+     * can be asked for it. `deb`/`rpm` carry both: a distribution ships `gjs` and
+     * `nodejs`, and the package declares whichever it execs.
+     *
+     * ⚠️ `flatpak` carries `gjs` ALONE, and that is a measured limit rather than
+     * a conservative default. `org.gnome.Platform` ships `gjs` and no `node`;
+     * Node exists only as `org.freedesktop.Sdk.Extension.node2x`, which puts
+     * `/usr/lib/sdk/node24/bin` on the **build** PATH — this repo's own
+     * `guides/flatpak-cli-tool.md` says so in those words. So a `--app node`
+     * Flatpak would install and die at `exec node`.
+     *
+     * That case was reachable: `assertLauncherMatchesInterpreter` is about the
+     * launcher agreeing with the DEPENDENCY, and a Flatpak has no dependency
+     * list, so the check is vacuous here — it compares `settings.app` against a
+     * launcher rendered from `settings.app`. Only the RUNTIME knows, and only
+     * this row can say.
+     */
+    interpreters: readonly ('gjs' | 'node')[];
+    /**
+     * Why this format's runtime provides {@link interpreters} and no more — the
+     * body of the refusal a project on the wrong interpreter gets.
+     *
+     * On the row rather than inside the refusal, and the incident is one line
+     * old: the refusal carried Flatpak's paragraph about `org.gnome.Platform`
+     * hardcoded, and the first macOS row printed it — telling somebody shipping a
+     * `.app` that `org.freedesktop.Sdk.Extension.node2x` puts node on the build
+     * path. Exactly the shape `installHint` moved out of `assertToolsInstalled`
+     * for, one field over.
+     *
+     * REQUIRED, including on the two rows that accept both interpreters and can
+     * therefore never print it. A row that answers "nothing here is restricted,
+     * and this is why" has ANSWERED; an optional field is one a sixth format can
+     * leave undefined while restricting `interpreters`, and the refusal would go
+     * back to having nothing to say.
+     */
+    interpreterGap: string;
     /** Where the project's licence text goes in this format's overlay. */
     licenseDest: (binaryName: string) => string;
     /**
@@ -137,6 +230,19 @@ export interface FormatDescriptor {
     archName: (arch: string, archIndependent: boolean) => string;
     /** Artifact filename, given the pack-time settings and the resolved arch label. */
     fileName: (settings: PackSettings, archLabel: string) => string;
+    /**
+     * Whether {@link fileName} names a FILE or a DIRECTORY.
+     *
+     * A `.deb`, an `.rpm` and a `.flatpak` are single files; a `<App>.app` is a
+     * directory that macOS treats as one object, and it is the first artifact in
+     * this table that is not a file. Recorded rather than inferred from the
+     * suffix, because `packOne` reports a SIZE and `statSync` on a directory
+     * answers 4096 on ext4 — a `.app` carrying a 20 MiB bundle would be printed
+     * as "4096 bytes", which is not a rounding error but a different number
+     * entirely. The `.dmg` over that same tree is `'file'` again, which is what
+     * makes this a property of the CONTAINER rather than "macOS is special".
+     */
+    artifactKind: 'file' | 'directory';
 }
 /** One shared-mime-info type definition (`gjsify.ship.mimeTypes`). */
 export interface ShipMimeType {
@@ -180,12 +286,16 @@ export interface ShipMimeType {
  *    `share/locale/<rel>`, and no packer reads the field. So translations
  *    cross in the payload, where they belong, and the `abs` path does not
  *    cross at all. This list being explicit is what caught that.
- *  - `name`, `kind`, `execArgs` — read by the planner and the metadata
- *    renderers, all of which have run by the time a stage exists. `appId` was
- *    on this line and MOVED: the Flatpak packer needs it at pack time twice
- *    over — it is the manifest's `id` and the ref `flatpak build-bundle`
- *    exports — and neither is derivable from the payload, because the desktop
- *    entry that carries the id is only staged for `kind: 'app'`.
+ *  - `kind`, `execArgs` — read by the planner and the metadata renderers, all of
+ *    which have run by the time a stage exists. `appId` was on this line and
+ *    MOVED: the Flatpak packer needs it at pack time twice over — it is the
+ *    manifest's `id` and the ref `flatpak build-bundle` exports — and neither is
+ *    derivable from the payload, because the desktop entry that carries the id
+ *    is only staged for `kind: 'app'`. `name` was on it too and moved for the
+ *    same kind of reason one milestone later: the macOS artifact IS
+ *    `<name>.app`, so the packing host has to be able to NAME it, and no other
+ *    field in this object can spell it (`binaryName` is the executable inside
+ *    the bundle, not the bundle).
  *  - `arch` — carried by the manifest's `target`, which is also the value a
  *    mismatched stage is refused on, so it lives in exactly one place.
  *  - `mimeTypes` — phase 1 renders the shared-mime-info document into the
@@ -198,6 +308,17 @@ export interface PackSettings {
     binaryName: string;
     /** Reverse-DNS application id — the Flatpak manifest's `id` and the exported ref. */
     appId: string;
+    /**
+     * Human-readable display name — and, on macOS, the `<App>.app` directory itself.
+     *
+     * On this side of the host boundary because the darwin packers cannot work
+     * without it: `macos-app`'s artifact is a directory called `${name}.app` and
+     * `macos-app-zip` wraps that directory, so a finishing host with the stage and
+     * nothing else still has to be able to spell it. Also what `Info.plist`'s
+     * `CFBundleName`/`CFBundleDisplayName` carry — see `layout.ts`'s
+     * `LayoutMetadataInput`.
+     */
+    name: string;
     /** Upstream version, normalised for package managers. */
     version: string;
     /** Package revision within one upstream version (deb revision / rpm release). */
@@ -219,8 +340,23 @@ export interface PackSettings {
     extraDepends: Record<DistroFormatId, string[]>;
     /** Project-supplied GI-namespace → package rows, filling gaps in the built-in table. */
     typelibPackages: Record<string, Record<DistroFormatId, string>>;
-    /** Minimum GJS the emitted dependency asks for. */
+    /**
+     * The interpreter the launcher execs, and therefore the one the package
+     * depends on. From `gjsify.app`; default `'gjs'`.
+     *
+     * ON `PackSettings`, not on `ShipSettings` alone, because BOTH halves need it
+     * and they must not answer it differently: `renderLauncher` writes
+     * `exec gjs -m` or `exec node` from this field, and `deriveDepends` seeds
+     * `gjs >= …` or `nodejs >= …` from the same one. Two sources here is the
+     * defect this field replaces — a filename heuristic once produced
+     * `Depends: gjs (>= 1.86), nodejs (>= 24)` on a package whose launcher execed
+     * gjs.
+     */
+    app: 'gjs' | 'node';
+    /** Minimum GJS the emitted dependency asks for. Used only for `app: 'gjs'`. */
     minGjsVersion: string;
+    /** Minimum Node major. Used only for `app: 'node'`. */
+    minNodeVersion: string;
     /** The Flatpak manifest's non-payload half, fully defaulted at stage time. */
     flatpak: ShipFlatpakSettings;
 }
@@ -260,8 +396,6 @@ export interface ShipFlatpakSettings {
 export interface ShipSettings extends PackSettings {
     /** Absolute path to the project being shipped. */
     projectDir: string;
-    /** Human-readable display name. */
-    name: string;
     /** Absolute path to the licence file, when one was found. */
     licenseFile?: string;
     /** `'app'` stages a desktop entry and an icon; `'cli'` stages neither. */
@@ -306,4 +440,15 @@ export interface ShipSettings extends PackSettings {
     outDir: string;
     /** Target architecture in `process.arch` spelling. */
     arch: string;
+    /**
+     * The OS whose LAYOUT this run assembles, from the `gjsify ship <os>`
+     * positional (ADR 0024 § A2).
+     *
+     * Beside `arch` and for the same reason: together they are the stage's
+     * `target`, the string `--expect-target <os>-<arch>` is compared against, and
+     * the pair a matrix leg is identified by. Deliberately NOT in
+     * {@link PackSettings} — the manifest's `target` carries it, so it lives in
+     * exactly one place on the far side of the host boundary.
+     */
+    layoutOs: HostOs;
 }

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

@@ -0,0 +1,7 @@
+/**
+ * Escape a value for XML element content or an attribute value.
+ *
+ * `&` FIRST, or the ampersands the four later replacements introduce are escaped
+ * again and `Ship & Co` comes out as `Ship & Co`.
+ */
+export declare function xmlEscape(value: string): string;