@gjsify/cli 0.43.0 → 0.45.0

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,108 @@ export interface ShipArtifact {
     /** Size in bytes. */
     size: number;
 }
-export type FormatId = 'deb' | 'rpm';
+/**
+ * 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.
+ *
+ * Not every `FormatId`, and this is where the difference is written down once
+ * instead of being rediscovered per call site. A `.deb` says
+ * `Depends: gir1.2-gtk-4.0`, an `.rpm` says `Requires: gtk4`, and both are
+ * package names in a distribution's namespace. A Flatpak has no such field: it
+ * declares ONE dependency, its runtime (`org.gnome.Platform//50`), in the
+ * manifest — and inside that runtime a typelib is either present or nothing on
+ * the system provides it, so there is no package to name and no gap a name
+ * could close.
+ *
+ * `Extract<…>` rather than a fresh literal union, so this cannot outlive
+ * `FormatId`: dropping a member there shrinks this and reds every table keyed on
+ * it. The other direction is covered by {@link FormatDescriptor.depends} being
+ * REQUIRED — a new format cannot be added without saying which side it is on.
+ */
+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).
+ *
+ * Three fields rather than one `hostOs`, because the three questions have
+ * different answers. `finishOn` is not the LAYOUT — a `<App>.app` tree is
+ * assembled anywhere while the `.dmg` around it needs macOS. `requiredTools` is
+ * not implied by `finishOn` — `.deb` and `.rpm` are written by this tree and
+ * exec nothing, which is the whole reason `rpm` could become an independent
+ * oracle and catch the dpkg-`$1` defect in the first artifact. And `oracle` is
+ * derivable from neither: a format built by the platform's own tool forfeits
+ * that independence unless a reader from a DIFFERENT implementation family
+ * exists, which is exactly what `selfReading` is the honest confession of.
+ */
+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: RequiredTools;
+    /**
+     * How to install {@link requiredTools}, in this format's own words.
+     *
+     * DATA, because the refusal that names it is one generic function. The
+     * first cut hardcoded `sudo dnf install flatpak flatpak-builder` inside
+     * `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 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: {
+        /** Readers from a DIFFERENT implementation family than the packer. */
+        readWith: readonly string[];
+        /** Where each reader runs. A Linux-runnable reader is worth more — every CI leg has one. */
+        readOn: readonly HostOs[];
+        /**
+         * No independent discriminator yet. Legal to DECLARE while a format is
+         * being built; illegal to release — `flatpak.spec.ts` is what turns that
+         * sentence into a red test, so flipping it is a decision somebody makes
+         * rather than a field nobody reads.
+         */
+        selfReading: boolean;
+    };
+}
 /**
  * Everything that is per-FORMAT, as data.
  *
@@ -46,8 +147,71 @@ export type FormatId = 'deb' | 'rpm';
  */
 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. */
+    host: HostRequirement;
+    /**
+     * The key this format's dependency list is spelled under, or `null` when its
+     * 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;
     /**
@@ -66,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 {
@@ -109,8 +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.
- *  - `appId`, `name`, `kind`, `execArgs` — read by the planner and the metadata
- *    renderers, all of which have run by the time a stage exists.
+ *  - `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
@@ -121,6 +306,19 @@ export interface ShipMimeType {
 export interface PackSettings {
     /** Package name: the `bin/` entry, the deb `Package:`, the rpm `Name:`. */
     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). */
@@ -139,26 +337,65 @@ export interface PackSettings {
     /** rpm `Group:`. */
     group: string;
     /** Extra runtime dependencies per format, appended to the derived set. */
-    extraDepends: {
-        deb: string[];
-        rpm: string[];
-    };
+    extraDepends: Record<DistroFormatId, string[]>;
     /** Project-supplied GI-namespace → package rows, filling gaps in the built-in table. */
-    typelibPackages: Record<string, {
-        deb: string;
-        rpm: string;
-    }>;
-    /** Minimum GJS the emitted dependency asks for. */
+    typelibPackages: Record<string, Record<DistroFormatId, string>>;
+    /**
+     * 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;
+}
+/**
+ * What the generated Flatpak manifest says about everything that is not the payload.
+ *
+ * Resolved — defaults applied — while the project is still in reach, because
+ * the defaults depend on `kind` and on `gjsify.flatpak`/`gjsify.ship.flatpak`,
+ * and the finishing host has neither.
+ *
+ * There is deliberately no `modules` / `extraModules` here. Under `ship` the
+ * module list IS the staged payload (ADR 0024 § 2: "a target that needs an
+ * extra file gets an overlay, never a branch in the staging code"), and an
+ * escape hatch that injects arbitrary build modules would put a second staging
+ * model back in the tree — which is the one thing § 8 gates the whole migration
+ * on. A project that genuinely needs to BUILD something inside the sandbox
+ * still has `gjsify flatpak init` + `gjsify flatpak build`, unchanged.
+ */
+export interface ShipFlatpakSettings {
+    /** Runtime id, e.g. `org.gnome.Platform`. */
+    runtime: string;
+    /** Runtime/SDK version, e.g. `50`. */
+    runtimeVersion: string;
+    /** SDK id, e.g. `org.gnome.Sdk`. */
+    sdk: string;
+    /** The branch the app is exported under — the last segment of `app/<id>/<arch>/<branch>`. */
+    branch: string;
+    sdkExtensions: string[];
+    /** Path components prepended to `PATH` inside the build sandbox. */
+    appendPath: string[];
+    /** Capabilities the finished app is granted. */
+    finishArgs: string[];
+    /** Cleanup globs applied to `/app` after the module has run. */
+    cleanup: string[];
 }
 /** The resolved, fully defaulted configuration for one `gjsify ship` run. */
 export interface ShipSettings extends PackSettings {
     /** Absolute path to the project being shipped. */
     projectDir: string;
-    /** Reverse-DNS application id — desktop entry, metainfo and icon basename. */
-    appId: 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. */
@@ -203,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;

package/lib/utils/ship/xml.js

@@ -0,0 +1,25 @@
+// The XML escape `gjsify ship`'s document renderers share.
+//
+// TWO COPIES BECAME ONE. `mime.ts` and `msi.ts` each grew their own — five
+// replacements, same entities, same order, byte-identical bodies — one milestone
+// apart, by people who never saw the other file. The second copy is where the
+// helper goes.
+//
+// `plist.ts` keeps its own and that divergence CARRIES something: a plist value
+// lands only in element CONTENT, so `"` and `'` are left as themselves rather
+// than becoming entities a human reading `Info.plist` has to decode. This one is
+// used in ATTRIBUTES too — a `.wxs` is almost nothing else — so it escapes both.
+/**
+ * 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 function xmlEscape(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}

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

@@ -0,0 +1,69 @@
+import type { PayloadEntry } from './payload.js';
+/** CRC-32 of a byte range, in ZIP's spelling (pre- and post-inverted). */
+export declare function crc32(data: Uint8Array): number;
+/**
+ * A Unix epoch second as the MS-DOS date and time pair ZIP stores.
+ *
+ * The format is from 1980 and cannot say anything earlier, and its seconds field
+ * holds HALF-seconds, so an odd second is not representable. Neither is refused:
+ * the stamp is metadata no reader in this repository asserts on, and failing a
+ * build because `SOURCE_DATE_EPOCH` named 1979 would reject an artifact over a
+ * display field. Earlier than 1980 is CLAMPED to it; the odd second is floored.
+ *
+ * UTC deliberately, not local time. A DOS stamp carries no zone, so reading it
+ * back as local time is the only convention available — and using the packing
+ * host's zone would mean two runners in different regions produce different bytes
+ * from one stage, which is exactly the property this module exists to hold.
+ */
+export declare function dosDateTime(epochSeconds: number): {
+    date: number;
+    time: number;
+};
+/** One entry to store, addressed by its path INSIDE the archive. */
+export interface ZipEntry {
+    /** Archive-relative, POSIX-separated. ZIP stores `/` on every platform. */
+    path: string;
+    /** POSIX mode bits, written into the external attributes' high 16 bits. */
+    mode: number;
+    data: Uint8Array;
+}
+/**
+ * Build a ZIP archive: local headers, then the central directory, then the EOCD.
+ *
+ * `mtime` is one stamp for every entry, taken from the caller. Per-file mtimes
+ * are deliberately not read off disk: an artifact upload does not carry them
+ * (`stage-manifest.ts`'s header), so re-stat'ing the stage on the packing host
+ * would stamp the archive with "whenever the download finished" and two hosts
+ * packing one stage would disagree.
+ *
+ * ENTRIES ARE SORTED BY PATH, and the caller's order is not trusted for the same
+ * reason `plan.ts` sorts: two runs over one payload must produce one byte
+ * sequence, and a `readdir` order is a filesystem's opinion.
+ *
+ * NO DIRECTORY ENTRIES. A ZIP may carry them and `unzip` recreates the tree from
+ * the file paths alone, so emitting them would add entries no reader here
+ * inspects and one more thing to keep deterministic. The consequence is stated
+ * rather than left to be discovered: an EMPTY directory inside a `.app` would not
+ * survive the archive — nothing in the payload can produce one, because
+ * `writeStage` only ever writes files.
+ *
+ * ZIP64 is NOT implemented, and the refusal below is what keeps that honest:
+ * past 4 GiB or 65535 entries the 32-bit fields silently wrap and the archive
+ * that comes out is well-formed and wrong. A loud limit is the better failure —
+ * the same argument `assertPayloadMatchesArch` makes one field over, where a
+ * label nothing compared to the payload produced an artifact `rpm` confirmed.
+ */
+export declare function buildZip(entries: readonly ZipEntry[], mtime: number): Uint8Array;
+/**
+ * The payload as zip entries, keeping each file's planned mode.
+ *
+ * `topLevel` names a directory every entry goes UNDER, and `''` means the payload
+ * paths already carry one. The two callers differ because their layouts do:
+ * a `<App>.app`'s staged paths already begin with the bundle directory
+ * (`Layout.root`), while a Windows program directory's do not — the stage IS its
+ * contents, because an installer chooses the parent. An archive without a top
+ * level expands into whatever directory the user happened to be in, scattering
+ * `app\`, `share\` and the launcher across it, and no listing of NAMES reads as
+ * wrong: every entry is individually correct.
+ */
+export declare function zipEntriesFromPayload(payload: readonly PayloadEntry[], topLevel?: string): ZipEntry[];