@gjsify/cli 0.42.0 → 0.43.0

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

@@ -1,4 +1,4 @@
-import type { ShipSettings } from './types.js';
+import type { PayloadFacts } from './payload.js';
 /**
  * The cache refreshes this payload makes necessary, each guarded by the tool's
  * presence and `|| true`.
@@ -6,8 +6,18 @@ import type { ShipSettings } from './types.js';
  * The caches belong to the distribution, not to us: on removal the helper may
  * already be gone, and a maintainer script that fails during a purge leaves a
  * package the user cannot uninstall.
+ *
+ * Keyed on the PAYLOAD, not on the settings. Each line refreshes exactly one
+ * directory, so the honest precondition is "did this package install anything
+ * into that directory" — which the payload answers and a project's file lists
+ * only approximate. They came apart in one measured case: a `kind: 'cli'`
+ * project with a `data/icons/` folder staged no icon at all (icons are an
+ * `'app'` thing in `planStage`) while `settings.iconFiles` was non-empty, so
+ * the postinst refreshed an icon cache for files that were never installed.
+ * The second reason is ADR 0024 § A2: those lists are absolute BUILD-host
+ * paths, and this code now also runs on a host that has only the staged tree.
  */
-export declare function cacheRefreshCommands(settings: ShipSettings, prefix: string): string[];
+export declare function cacheRefreshCommands(facts: PayloadFacts, prefix: string): string[];
 /**
  * dpkg maintainer scripts, keyed by their `control.tar` filename.
  *
@@ -15,7 +25,7 @@ export declare function cacheRefreshCommands(settings: ShipSettings, prefix: str
  * and several abort paths, and on an upgrade the incoming package's `postinst`
  * refreshes the caches anyway.
  */
-export declare function renderDebScripts(settings: ShipSettings, prefix: string): Record<string, string>;
+export declare function renderDebScripts(facts: PayloadFacts, prefix: string): Record<string, string>;
 /**
  * rpm scriptlets, for the `POSTIN` / `POSTUN` header tags.
  *
@@ -25,7 +35,7 @@ export declare function renderDebScripts(settings: ShipSettings, prefix: string)
  * work rather than a wrong result, where guarding on `[ $1 -eq 0 ]` would be
  * one more place to get the convention backwards.
  */
-export declare function renderRpmScriptlets(settings: ShipSettings, prefix: string): {
+export declare function renderRpmScriptlets(facts: PayloadFacts, prefix: string): {
     post?: string;
     postun?: string;
 };

package/lib/utils/ship/scripts.js

@@ -18,22 +18,40 @@
  * The caches belong to the distribution, not to us: on removal the helper may
  * already be gone, and a maintainer script that fails during a purge leaves a
  * package the user cannot uninstall.
+ *
+ * Keyed on the PAYLOAD, not on the settings. Each line refreshes exactly one
+ * directory, so the honest precondition is "did this package install anything
+ * into that directory" — which the payload answers and a project's file lists
+ * only approximate. They came apart in one measured case: a `kind: 'cli'`
+ * project with a `data/icons/` folder staged no icon at all (icons are an
+ * `'app'` thing in `planStage`) while `settings.iconFiles` was non-empty, so
+ * the postinst refreshed an icon cache for files that were never installed.
+ * The second reason is ADR 0024 § A2: those lists are absolute BUILD-host
+ * paths, and this code now also runs on a host that has only the staged tree.
  */
-export function cacheRefreshCommands(settings, prefix) {
+export function cacheRefreshCommands(facts, prefix) {
     const refreshes = [];
-    if (settings.kind === 'app') {
+    if (facts.hasDesktopEntry) {
         refreshes.push({
             probe: 'update-desktop-database',
             run: `update-desktop-database -q ${prefix}/share/applications`,
         });
     }
-    if (settings.iconFiles.length > 0) {
+    if (facts.hasIcons) {
         refreshes.push({
             probe: 'gtk-update-icon-cache',
             run: `gtk-update-icon-cache -q -t -f ${prefix}/share/icons/hicolor`,
         });
     }
-    if (settings.schemaFiles.length > 0) {
+    if (facts.hasMimeTypes) {
+        // Without this the document is installed and the type still does not exist: detection runs
+        // off the compiled cache in `share/mime/`, not off the packages directory.
+        refreshes.push({
+            probe: 'update-mime-database',
+            run: `update-mime-database ${prefix}/share/mime`,
+        });
+    }
+    if (facts.hasSchemas) {
         refreshes.push({
             probe: 'glib-compile-schemas',
             run: `glib-compile-schemas ${prefix}/share/glib-2.0/schemas`,
@@ -48,8 +66,8 @@ export function cacheRefreshCommands(settings, prefix) {
  * and several abort paths, and on an upgrade the incoming package's `postinst`
  * refreshes the caches anyway.
  */
-export function renderDebScripts(settings, prefix) {
-    const commands = cacheRefreshCommands(settings, prefix);
+export function renderDebScripts(facts, prefix) {
+    const commands = cacheRefreshCommands(facts, prefix);
     if (commands.length === 0)
         return {};
     const body = commands.map((line) => `    ${line}`).join('\n');
@@ -67,8 +85,8 @@ export function renderDebScripts(settings, prefix) {
  * work rather than a wrong result, where guarding on `[ $1 -eq 0 ]` would be
  * one more place to get the convention backwards.
  */
-export function renderRpmScriptlets(settings, prefix) {
-    const commands = cacheRefreshCommands(settings, prefix);
+export function renderRpmScriptlets(facts, prefix) {
+    const commands = cacheRefreshCommands(facts, prefix);
     if (commands.length === 0)
         return {};
     const body = `${commands.join('\n')}\n`;

package/lib/utils/ship/settings.js

@@ -9,6 +9,7 @@
 // Precedence is uniform: CLI flag > `gjsify.ship` > `gjsify.flatpak` (metadata
 // only) > derived from package.json. Never a yargs `default:`, which is
 // indistinguishable from a value the user typed and would clobber the config.
+import { validateMimeTypes } from './mime.js';
 import { basename } from 'node:path';
 import { DEFAULT_GJS_FLOOR } from './depends.js';
 import { assertRelease, normaliseVersion } from './version.js';
@@ -32,6 +33,17 @@ export function resolveShipSettings(input) {
     // `gjsify.flatpak` key-by-key is exactly the fallback ADR 0024 § 8 asks
     // for. The non-metadata keys each block carries ride along unread.
     const metadata = { ...flatpak, ...definedOnly(ship) };
+    // A type this package DEFINES is also a type it handles. Folding it into `provides.mimetypes`
+    // here means the desktop entry and the metainfo need no knowledge of `mimeTypes` at all: they
+    // already render `MimeType=` (with the `%f` field code) and `<mediatype>` from that one field.
+    // Doing it the other way — leaving the two lists independent — makes "defined but not handled"
+    // a state you can reach by omission, and that state installs cleanly and does nothing.
+    const mimeTypes = ship.mimeTypes ?? [];
+    if (mimeTypes.length > 0) {
+        validateMimeTypes(mimeTypes);
+        const handled = new Set([...(metadata.provides?.mimetypes ?? []), ...mimeTypes.map((m) => m.type)]);
+        metadata.provides = { ...metadata.provides, mimetypes: [...handled] };
+    }
     const binaryName = ship.binaryName ?? deriveBinaryName(pkg.name);
     const appId = ship.appId ?? flatpak.appId ?? reverseDnsOrThrow(pkg.name, binaryName);
     const name = metadata.name ?? titleCase(binaryName);
@@ -75,6 +87,7 @@ export function resolveShipSettings(input) {
         section: ship.section ?? sections.section,
         group: ship.group ?? sections.group,
         kind,
+        mimeTypes,
         extraDepends: { deb: ship.depends?.deb ?? [], rpm: ship.depends?.rpm ?? [] },
         typelibPackages: ship.typelibPackages ?? {},
         bundlePath: discovered.bundlePath,

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

@@ -0,0 +1,154 @@
+import type { FormatDescriptor, FormatId, 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";
+/**
+ * The schema this CLI writes and the only one it reads.
+ *
+ * A stage is a short-lived intermediate between two jobs of ONE run, not an
+ * archive, so there is no migration path in either direction and both
+ * mismatches are refused rather than guessed at — see {@link readStageManifest}.
+ * Bump it whenever a field's MEANING changes, not when one is added that an
+ * older reader would simply ignore; a reader that ignores a field it does not
+ * know is exactly how a mode plan silently loses an entry.
+ */
+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.
+ */
+export declare const STAGE_LAYOUT_OS = "linux";
+/** What this stage was assembled FOR, in the repo-wide `${process.platform}-${process.arch}` spelling. */
+export interface StageTarget {
+    os: string;
+    arch: string;
+}
+/** One staged path, its planned mode, and the size it had when the stage was written. */
+export interface StageFileRecord extends StagedMode {
+    bytes: number;
+}
+/** One pre-rendered overlay file. Text only — see {@link writeStageManifest}. */
+export interface StageOverlayFile extends StagedMode {
+    text: string;
+}
+export interface StageManifest {
+    schema: number;
+    /** The tool that assembled the stage, so a mixed-version pipeline is answerable after the fact. */
+    tool: {
+        name: string;
+        version: string;
+    };
+    target: StageTarget;
+    /** The formats phase 1 rendered an overlay closure for. */
+    formats: FormatId[];
+    /** The one build stamp every header and every rendered file shares. */
+    mtime: number;
+    /** GI namespaces the bundle imports, `Ns-Version` where the specifier pins one. */
+    namespaces: string[];
+    settings: PackSettings;
+    staged: StageFileRecord[];
+    overlay: Partial<Record<FormatId, StageOverlayFile[]>>;
+}
+export interface StageManifestInput {
+    /** Absolute path of the stage root, already written. */
+    stageDir: string;
+    settings: ShipSettings;
+    formats: readonly FormatDescriptor[];
+    mtime: number;
+    namespaces: readonly string[];
+    staged: readonly StagedFile[];
+    /** Per-format overlay, as `planOverlay` produced it. */
+    overlay: ReadonlyMap<FormatId, readonly StagedFile[]>;
+}
+/**
+ * The half of {@link ShipSettings} that crosses the host boundary.
+ *
+ * Written out field by field rather than spread: a spread would carry
+ * `projectDir`, `bundlePath`, `bundleDir`, `iconFiles`, `schemaFiles`,
+ * `extraFiles` and `licenseFile` — seven absolute paths from the assembling
+ * host — into a file whose whole purpose is to be read somewhere else. The
+ * explicit list is also what makes adding a field a decision: see the comment
+ * on {@link PackSettings} for what belongs on each side.
+ */
+export declare function toPackSettings(settings: ShipSettings): PackSettings;
+/** Absolute path of a stage's manifest. */
+export declare function stageManifestPath(stageDir: string): string;
+/** `linux-x64`. One spelling repo-wide (root AGENTS.md § Runtime & platform model). */
+export declare function formatTarget(target: StageTarget): string;
+/**
+ * Write the manifest at the stage root, AFTER the tree itself.
+ *
+ * `bytes` is stat'ed off the written tree rather than taken from the plan: the
+ * plan holds a source path or a string, and what the packing host will compare
+ * against is what actually landed on disk here.
+ */
+export declare function writeStageManifest(input: StageManifestInput): StageManifest;
+/**
+ * Read and validate a stage's manifest.
+ *
+ * Every field is checked, because this file is the only thing standing between
+ * "a directory someone pointed us at" and a signed-looking `.deb`. A missing
+ * `staged` entry would reach `readStage` as a mode nobody planned; a `mode` that
+ * arrived as a string would reach `chmod` as `NaN`.
+ */
+export declare function readStageManifest(stageDir: string): StageManifest;
+/** The overlay for one format, in the shape `writeStage` takes. */
+export declare function overlayFiles(manifest: StageManifest, format: FormatId): StagedFile[];
+/**
+ * Refuse a stage that is not the one this job was told to pack.
+ *
+ * WHAT THIS IS: a matrix-leg mix-up check. It catches a finish job that
+ * downloaded the wrong artifact — the leg that forgot to route — and nothing
+ * more. It is opt-in (no flag, no check) and it compares two strings the same
+ * pipeline wrote one job apart, so treat a green run as "this is the stage I
+ * asked for", never as "this stage is correctly labelled".
+ *
+ * WHAT THIS IS NOT: the guard its precedent
+ * (`packages/node-gi/scripts/verify-bundle-manifest.mjs --expect-host-target`)
+ * provides. That script compares a bundle to `process.platform`/`process.arch`
+ * because the runner BUILT it, so the machine is the right second opinion.
+ * Here the stage arrives from another host by design, so a host comparison
+ * would refuse a legal use — measured: an `arm64`-labelled stage packs on this
+ * x64 host at exit 0 with correct bytes, because both packers are pure JS.
+ *
+ * The class that precedent guards — a label and the bytes under it disagreeing
+ * — is NOT guarded here, and `target.arch` cannot guard it: it is defaulted
+ * from `process.arch` only when `--arch` is absent, so the moment an operator
+ * says which leg they are on, `target.arch` is that operator's claim and
+ * nothing compares it to a machine or to a byte. Measured BEFORE
+ * {@link assertPayloadMatchesArch} existed: a stage carrying an x86-64 `.so`,
+ * assembled `--stage --arch arm64` and packed `--expect-target linux-arm64`,
+ * exited 0 and produced an `aarch64` rpm whose only `.so` was `e_machine=0x3e`.
+ * The same command in this tree now exits 1 and writes nothing — kept in the
+ * past tense because it is the reason the guard below it exists, not a
+ * description of what this function does.
+ *
+ * That class is guarded one layer down instead, where the oracle is free and
+ * cannot be wrong about a machine it never saw: {@link assertPayloadMatchesArch}
+ * in `payload.ts` reads ELF `e_machine` / Mach-O `cputype` out of the payload
+ * and refuses a label the bytes contradict. Payload-versus-label goes red on
+ * the mislabelled stage AND stays green on the legitimate cross-host pack;
+ * host-versus-label can only do one of the two.
+ */
+export declare function assertExpectedTarget(manifest: StageManifest, expected: string | undefined): void;
+/** Refuse a format the stage carries no overlay closure for. */
+export declare function assertFormatsStaged(manifest: StageManifest, formats: readonly FormatDescriptor[]): void;
+/**
+ * The build stamp the packing host uses: the stage's, always.
+ *
+ * A `SOURCE_DATE_EPOCH` set only in the finish job would silently produce a
+ * different artifact than the same stage packed on the assembling host, which
+ * is the one property the two-phase split has to keep. It is a warning rather
+ * than a refusal because the honest fix ("set it in both jobs or in neither")
+ * is the caller's, and refusing would break a runner that exports it globally.
+ */
+export declare function resolveStageMtime(manifest: StageManifest, env?: Record<string, string | undefined>): {
+    mtime: number;
+    warnings: string[];
+};
+/** One actionable line when the two phases ran different gjsify versions. */
+export declare function warnOnToolSkew(manifest: StageManifest): string[];