@gjsify/cli 0.42.0 → 0.43.0

package/lib/utils/ship/discover.js

@@ -4,8 +4,8 @@
 // so `settings.ts` and `plan.ts` can stay pure. Every probe has a configured
 // override; the probes exist so a project that follows the GNOME convention
 // (`data/icons/hicolor/…`, `data/*.gschema.xml`) needs no configuration at all.
-import { existsSync, readdirSync, statSync } from 'node:fs';
-import { isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
 import { LICENSE_FILE_NAMES } from './settings.js';
 const ICON_EXTENSIONS = ['.svg', '.png'];
 export function discoverPayload(input) {
@@ -189,6 +189,34 @@ function discoverSchemas(projectDir, configured) {
     }
     return [];
 }
+/**
+ * The licence text this package ships — searched UP the tree, not just beside
+ * `package.json`.
+ *
+ * A monorepo package does not carry its own copy. `packages/infra/cli`
+ * declares `"license": "MIT"` and the text lives one `LICENSE` up at the
+ * repository root, shared by sixty-odd packages; searching `projectDir` alone
+ * found nothing, `planOverlay` turned "nothing" into an empty overlay, and the
+ * `.deb` shipped without the `/usr/share/doc/<pkg>/copyright` that Debian
+ * Policy § 12.5 requires. Nothing downstream noticed: `dpkg-deb --info` prints
+ * a clean control file and `dpkg -i` installs it. It took the first leg that
+ * ran a real `lintian` to say so.
+ *
+ * WHERE THE SEARCH STOPS is the whole design. It climbs to the first ancestor
+ * that is a project root — one holding `.git`, or a `package.json` declaring
+ * `workspaces` — and searches that directory too, then stops. Above that line
+ * a `LICENSE` belongs to some unrelated tree that happens to be a parent
+ * directory (`~/Projekte/LICENSE` is not yours), and packaging its text would
+ * make a specific false legal claim. When NO marker is found the search is the
+ * project directory alone: without a marker there is no way to tell where the
+ * project ends, and guessing wrong is the same false claim.
+ *
+ * What this cannot check is whether the inherited text is the RIGHT licence
+ * for this package — an Apache-2.0 package inside an MIT monorepo would
+ * inherit the wrong one. Reading an SPDX identifier out of licence prose is
+ * not something to guess at, so the caller PRINTS the inherited path instead
+ * (see `commands/ship.ts`), and `gjsify.ship.licenseFile` overrides it.
+ */
 function discoverLicense(projectDir, configured) {
     if (configured !== undefined) {
         const target = resolve(projectDir, configured);
@@ -197,13 +225,51 @@ function discoverLicense(projectDir, configured) {
         }
         return target;
     }
-    for (const name of LICENSE_FILE_NAMES) {
-        const target = join(projectDir, name);
-        if (existsSync(target))
-            return target;
+    for (const dir of licenseSearchDirs(projectDir)) {
+        for (const name of LICENSE_FILE_NAMES) {
+            const target = join(dir, name);
+            if (existsSync(target))
+                return target;
+        }
     }
     return undefined;
 }
+/** `projectDir` first, then each ancestor up to and including the project root. */
+function licenseSearchDirs(projectDir) {
+    const dirs = [];
+    for (let current = projectDir;;) {
+        dirs.push(current);
+        if (isProjectRoot(current))
+            return dirs;
+        const parent = dirname(current);
+        if (parent === current)
+            return [projectDir];
+        current = parent;
+    }
+}
+/**
+ * Is this the top of the tree the project belongs to?
+ *
+ * `.git` is tested with `existsSync` rather than `statSync().isDirectory()`
+ * because in a git WORKTREE it is a file, and this repository is developed in
+ * worktrees.
+ */
+function isProjectRoot(dir) {
+    if (existsSync(join(dir, '.git')))
+        return true;
+    const manifest = join(dir, 'package.json');
+    if (!existsSync(manifest))
+        return false;
+    try {
+        return JSON.parse(readFileSync(manifest, 'utf-8')).workspaces !== undefined;
+    }
+    catch {
+        // A malformed `package.json` in some ancestor is not this command's
+        // business, and it must not turn a licence search into a ship failure.
+        // Not a root, then: the climb continues and `.git` still stops it.
+        return false;
+    }
+}
 /**
  * Every regular file under `dir`, as POSIX-separated relative paths.
  *

package/lib/utils/ship/formats.js

@@ -58,7 +58,15 @@ export const FORMATS = {
         fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.${archLabel}.rpm`,
     },
 };
-export const FORMAT_IDS = ['deb', 'rpm'];
+// DERIVED, never a second list. `FORMATS` is `Record<FormatId, …>`, so the
+// compiler already refuses a `FormatId` with no descriptor — reading the keys
+// back inherits that guarantee for free. Written out by hand this was the one
+// unbound copy of the vocabulary: adding a format to `FormatId` and `FORMATS`
+// compiled fine and left this list short, which would have made the new format
+// absent from the default targets (`ship.ts` uses it as the `??` fallback),
+// missing from `--help`, and REFUSED by `readStage` as an unknown id.
+// Insertion order is stable for string keys, and `resolveFormats` sorts anyway.
+export const FORMAT_IDS = Object.keys(FORMATS);
 /** Parse `--target deb,rpm` into a sorted, deduplicated descriptor list. */
 export function resolveFormats(raw) {
     const names = raw

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

@@ -0,0 +1,19 @@
+import type { ShipMimeType } from './types.js';
+/**
+ * Validate the declared types, throwing on anything that would install and then not work.
+ *
+ * Each refusal is a silent failure made loud:
+ *  - a malformed type name is written into the XML and ignored by `update-mime-database`;
+ *  - a glob without `*.` never matches (`bauplan` matches only a file called exactly that);
+ *  - a type with no glob and no parent type can never be DETECTED, so it is registered and unused;
+ *  - a duplicate definition makes which comment wins depend on document order.
+ */
+export declare function validateMimeTypes(types: readonly ShipMimeType[]): void;
+/**
+ * The shared-mime-info document for `types`.
+ *
+ * One file per package, named after the app id, because `share/mime/packages/` is shared: a generic
+ * name is a collision with whatever another package put there — the same reason the schema staging
+ * uses the app id.
+ */
+export declare function renderMimePackage(types: readonly ShipMimeType[]): string;

package/lib/utils/ship/mime.js

@@ -0,0 +1,89 @@
+// Defining a file type for the system — the half `MimeType=` cannot do on its own.
+//
+// A desktop entry's `MimeType=` says "I open this type". It does NOT say the type EXISTS. For a
+// standard type that is fine, because the distribution's shared-mime-info already defines it; for a
+// type of the project's own it is not, and the failure is the quietest kind there is: nothing knows
+// what a `.bauplan` file is, so the file manager never assigns the type, `MimeType=` matches
+// nothing, and a double-click does nothing at all. No error is printed and no log line is written —
+// the association simply never fires, which is indistinguishable from "the app is not installed".
+//
+// So a project that invents a type also ships a shared-mime-info document, and the package refreshes
+// the MIME cache on install (see `scripts.ts`) — an unrefreshed cache is the same silence again.
+/** XML text escaping. Only the five that matter in element content and attributes. */
+function esc(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+const TYPE_RE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/;
+/**
+ * Validate the declared types, throwing on anything that would install and then not work.
+ *
+ * Each refusal is a silent failure made loud:
+ *  - a malformed type name is written into the XML and ignored by `update-mime-database`;
+ *  - a glob without `*.` never matches (`bauplan` matches only a file called exactly that);
+ *  - a type with no glob and no parent type can never be DETECTED, so it is registered and unused;
+ *  - a duplicate definition makes which comment wins depend on document order.
+ */
+export function validateMimeTypes(types) {
+    const seen = new Set();
+    for (const entry of types) {
+        if (!TYPE_RE.test(entry.type)) {
+            throw new Error(`gjsify ship: \`gjsify.ship.mimeTypes\` has an invalid type "${entry.type}". ` +
+                'Expected `<media>/<subtype>`, e.g. `application/x-bauplan` — update-mime-database ' +
+                'ignores a malformed name, so the type would install and never resolve.');
+        }
+        if (seen.has(entry.type)) {
+            throw new Error(`gjsify ship: \`gjsify.ship.mimeTypes\` defines ${entry.type} twice. ` +
+                'Which comment and glob set win would depend on document order.');
+        }
+        seen.add(entry.type);
+        if (entry.comment.trim() === '') {
+            throw new Error(`gjsify ship: ${entry.type} has an empty \`comment\`. A file manager then shows the ` +
+                'user the raw type string instead of a name.');
+        }
+        for (const glob of entry.globs ?? []) {
+            if (!glob.includes('*') && !glob.includes('?') && !glob.includes('[')) {
+                throw new Error(`gjsify ship: ${entry.type} has the glob "${glob}", which matches only a file ` +
+                    `named exactly that. A suffix pattern is written \`*.${glob.replace(/^\.+/, '')}\`.`);
+            }
+        }
+        if ((entry.globs ?? []).length === 0 && entry.subClassOf === undefined) {
+            throw new Error(`gjsify ship: ${entry.type} declares neither \`globs\` nor \`subClassOf\`, so nothing ` +
+                'can ever match it. The type would be registered and then never assigned to a file.');
+        }
+    }
+}
+/**
+ * The shared-mime-info document for `types`.
+ *
+ * One file per package, named after the app id, because `share/mime/packages/` is shared: a generic
+ * name is a collision with whatever another package put there — the same reason the schema staging
+ * uses the app id.
+ */
+export function renderMimePackage(types) {
+    const body = types
+        .map((entry) => {
+        const lines = [`  <mime-type type="${esc(entry.type)}">`, `    <comment>${esc(entry.comment)}</comment>`];
+        if (entry.subClassOf !== undefined) {
+            lines.push(`    <sub-class-of type="${esc(entry.subClassOf)}"/>`);
+        }
+        for (const glob of entry.globs ?? []) {
+            lines.push(`    <glob pattern="${esc(glob)}"/>`);
+        }
+        if (entry.genericIcon !== undefined) {
+            lines.push(`    <generic-icon name="${esc(entry.genericIcon)}"/>`);
+        }
+        lines.push('  </mime-type>');
+        return lines.join('\n');
+    })
+        .join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
+${body}
+</mime-info>
+`;
+}

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

@@ -16,8 +16,84 @@ export interface PayloadEntry {
  * what `rpm -qi` then shows a user, and an artifact that looks broken is a
  * support question. The mtime keeps the property that matters (pack the same
  * build twice, get the same bytes) while saying something true.
+ *
+ * Only the ASSEMBLING host runs this. A stage records the answer it got
+ * (`.gjsify-ship-stage.json` → `mtime`) and the packing host reuses it: an
+ * artifact upload does not carry mtimes, so re-stat'ing the stage there would
+ * stamp every header with "whenever the download finished" and quietly destroy
+ * the reproducibility this function exists to protect.
  */
 export declare function buildTimestamp(bundlePath: string, env?: Record<string, string | undefined>): number;
+/**
+ * What the payload itself says about what it installs.
+ *
+ * Every field here used to be answered from the SETTINGS — `settings.iconFiles.length > 0`,
+ * `settings.schemaFiles.length > 0`, `settings.typelibFiles` — i.e. from lists of absolute paths
+ * on the BUILD host. Two things were wrong with that, and the second is why this function exists
+ * at all:
+ *
+ *  1. It answered a different question than the one being asked. `cacheRefreshCommands` emits
+ *     `gtk-update-icon-cache <prefix>/share/icons/hicolor` — the honest precondition is "did this
+ *     package install anything into that directory", not "did the project have icon files lying
+ *     around". They come apart for a `kind: 'cli'` project with a `data/icons/` folder: the
+ *     planner stages no icon (icons are an `'app'` thing), the settings still listed them, and the
+ *     postinst refreshed a cache for files that were never installed.
+ *  2. An absolute build-host path cannot cross to the host that packs the artifact
+ *     (ADR 0024 § A2). Carrying `iconFiles: ["/home/…/icon.svg"]` in a stage manifest so that
+ *     `.length > 0` can be read on another machine is authoring a value that is measurable right
+ *     there in the tree.
+ *
+ * Path-only, on purpose — `isArchIndependent` is the sibling that reads BYTES, and the two answer
+ * different questions from the same payload. The same split as `plan.ts`'s `isExecutableAsset`
+ * (by name) versus this module's magic sniffing (by content).
+ */
+export interface PayloadFacts {
+    /** The payload installs a `share/applications/*.desktop`. */
+    hasDesktopEntry: boolean;
+    /** The payload installs into `share/icons/hicolor/`. */
+    hasIcons: boolean;
+    /** The payload installs a compiled-on-install `share/glib-2.0/schemas/*.gschema.xml`. */
+    hasSchemas: boolean;
+    /** The payload installs a `share/mime/packages/*.xml`, so the mime cache needs rebuilding. */
+    hasMimeTypes: boolean;
+    /** Prefix-relative paths of the typelibs the payload carries itself. */
+    bundledTypelibs: string[];
+}
+/**
+ * Read {@link PayloadFacts} off a payload or off a plan.
+ *
+ * Takes anything with a `path`, so the assembling phase can ask the same
+ * question of the PLAN (before the tree is read back) that the packing phase
+ * asks of the payload. One function, so the two phases cannot disagree about
+ * whether a package installs a schema.
+ */
+export declare function readPayloadFacts(entries: readonly {
+    path: string;
+}[]): PayloadFacts;
+/**
+ * The interpreters the payload's own executables need, read off their shebangs.
+ *
+ * An interpreter is a dependency like any other, and rpm expects it declared:
+ * `rpmbuild`'s file-based generator emits one `Requires` per executable
+ * shebang, with the `RPMSENSE_FIND_REQUIRES` sense that says "derived, not
+ * declared". Measured on Fedora 44 against a package whose only file is a
+ * `#!/bin/sh` script: `rpm -qp --requires` → `/usr/bin/sh 16384`.
+ *
+ * The LITERAL path, not a resolved one. `rpmbuild` prints `/usr/bin/sh` there
+ * because it resolved `/bin` through the symlink of the usrmerged host it ran
+ * on; this writer has no target host to resolve against (ADR 0024 § A1 — the
+ * packers are pure JavaScript and run anywhere), and `/bin/sh` is satisfied on
+ * both layouts: measured on Fedora 44, `rpm -q --whatprovides /bin/sh` and
+ * `/usr/bin/sh` both answer `bash`. It is also the spelling the scriptlet
+ * requirements already use.
+ *
+ * EXECUTABLE files only, which is the same rule `rpmbuild` applies. A GJS
+ * bundle staged 0644 carries `#!/usr/bin/env -S gjs -m` for the days it is run
+ * directly, but nothing in the installed package executes it as a program — the
+ * launcher `exec`s `gjs` with it as an argument — so declaring `/usr/bin/env`
+ * for it would be a dependency on a path this package never uses.
+ */
+export declare function readShebangInterpreters(payload: readonly PayloadEntry[]): string[];
 /**
  * Does the payload contain anything architecture-specific?
  *

package/lib/utils/ship/payload.js

@@ -16,6 +16,12 @@ import { statSync } from 'node:fs';
  * what `rpm -qi` then shows a user, and an artifact that looks broken is a
  * support question. The mtime keeps the property that matters (pack the same
  * build twice, get the same bytes) while saying something true.
+ *
+ * Only the ASSEMBLING host runs this. A stage records the answer it got
+ * (`.gjsify-ship-stage.json` → `mtime`) and the packing host reuses it: an
+ * artifact upload does not carry mtimes, so re-stat'ing the stage there would
+ * stamp every header with "whenever the download finished" and quietly destroy
+ * the reproducibility this function exists to protect.
  */
 export function buildTimestamp(bundlePath, env = process.env) {
     const raw = env.SOURCE_DATE_EPOCH;
@@ -28,6 +34,72 @@ export function buildTimestamp(bundlePath, env = process.env) {
     }
     return Math.floor(statSync(bundlePath).mtimeMs / 1000);
 }
+/**
+ * Read {@link PayloadFacts} off a payload or off a plan.
+ *
+ * Takes anything with a `path`, so the assembling phase can ask the same
+ * question of the PLAN (before the tree is read back) that the packing phase
+ * asks of the payload. One function, so the two phases cannot disagree about
+ * whether a package installs a schema.
+ */
+export function readPayloadFacts(entries) {
+    const paths = entries.map((entry) => entry.path);
+    return {
+        hasDesktopEntry: paths.some((path) => path.startsWith('share/applications/') && path.endsWith('.desktop')),
+        hasIcons: paths.some((path) => path.startsWith('share/icons/hicolor/')),
+        hasSchemas: paths.some((path) => path.startsWith('share/glib-2.0/schemas/') && path.endsWith('.gschema.xml')),
+        hasMimeTypes: paths.some((path) => path.startsWith('share/mime/packages/') && path.endsWith('.xml')),
+        // Anywhere in the payload, not only `lib/<name>/gi/`: `gjsify.ship.extraFiles` can place
+        // one elsewhere, and a typelib the package carries is a typelib the package must not also
+        // declare a distro dependency for, wherever it sits.
+        bundledTypelibs: paths.filter((path) => path.endsWith('.typelib')),
+    };
+}
+/**
+ * The interpreters the payload's own executables need, read off their shebangs.
+ *
+ * An interpreter is a dependency like any other, and rpm expects it declared:
+ * `rpmbuild`'s file-based generator emits one `Requires` per executable
+ * shebang, with the `RPMSENSE_FIND_REQUIRES` sense that says "derived, not
+ * declared". Measured on Fedora 44 against a package whose only file is a
+ * `#!/bin/sh` script: `rpm -qp --requires` → `/usr/bin/sh 16384`.
+ *
+ * The LITERAL path, not a resolved one. `rpmbuild` prints `/usr/bin/sh` there
+ * because it resolved `/bin` through the symlink of the usrmerged host it ran
+ * on; this writer has no target host to resolve against (ADR 0024 § A1 — the
+ * packers are pure JavaScript and run anywhere), and `/bin/sh` is satisfied on
+ * both layouts: measured on Fedora 44, `rpm -q --whatprovides /bin/sh` and
+ * `/usr/bin/sh` both answer `bash`. It is also the spelling the scriptlet
+ * requirements already use.
+ *
+ * EXECUTABLE files only, which is the same rule `rpmbuild` applies. A GJS
+ * bundle staged 0644 carries `#!/usr/bin/env -S gjs -m` for the days it is run
+ * directly, but nothing in the installed package executes it as a program — the
+ * launcher `exec`s `gjs` with it as an argument — so declaring `/usr/bin/env`
+ * for it would be a dependency on a path this package never uses.
+ */
+export function readShebangInterpreters(payload) {
+    const found = new Set();
+    for (const entry of payload) {
+        if ((entry.mode & 0o111) === 0)
+            continue;
+        const interpreter = readShebang(entry.data);
+        if (interpreter !== null)
+            found.add(interpreter);
+    }
+    return [...found].sort();
+}
+/** The absolute interpreter path of a `#!` line, or `null` when there is none to read. */
+function readShebang(data) {
+    if (data[0] !== 0x23 || data[1] !== 0x21)
+        return null; // `#!`
+    // A shebang is one LINE; reading further would let a long file's contents
+    // decide how much work this does. 256 bytes is above every real one and is
+    // what Linux itself truncates at (BINPRM_BUF_SIZE).
+    const line = new TextDecoder().decode(data.subarray(2, Math.min(data.byteLength, 256))).split('\n')[0] ?? '';
+    const interpreter = line.trim().split(/\s+/)[0] ?? '';
+    return interpreter.startsWith('/') ? interpreter : null;
+}
 /**
  * Does the payload contain anything architecture-specific?
  *
@@ -44,6 +116,23 @@ export function isArchIndependent(payload) {
 // values this repository can actually produce are listed; an unknown one reads
 // as "cannot tell" rather than as a mismatch, because refusing an artifact over
 // a machine constant nobody here emits would be a guess wearing a gate's clothes.
+// The machine values this project actually ships packages for — no more. A value
+// missing here makes `readBinaryArch` return null, and null is SILENT, so an
+// absent row costs nothing but a check that does not fire.
+//
+// `EM_MIPS` (0x08) is absent for that reason and no other. An earlier version of
+// this comment claimed it was absent because one value covers `mips` and
+// `mipsel` and the row would have to guess; that was wrong three times over, and
+// is corrected here rather than deleted because it is the kind of reasoning that
+// gets re-derived: (1) `mipsel` IS little-endian MIPS, so the discriminator is
+// `EI_DATA`, which `readBinaryArch` reads four lines below; (2) it could not
+// "refuse a correct pack" either way, because `formats.ts` has no `mips` row in
+// `DEBIAN_ARCH`/`RPM_ARCH`, so `archName` throws before any label is written;
+// and (3) the principle it invoked is already broken one row down — `0x16` maps
+// to `s390x`, but `EM_S390` is emitted by 31-bit `s390` too, and its
+// discriminator is `EI_CLASS` at offset 4, which this function does NOT read.
+// That row is the ambiguous one. Unreachable today (nothing here builds s390),
+// but it is the row to fix first if this table ever grows.
 const ELF_MACHINE_TO_ARCH = {
     0x03: 'ia32',
     0x15: 'ppc64',
@@ -121,7 +210,8 @@ export function assertPayloadMatchesArch(payload, arch) {
             'anything.\n' +
             `    A package labelled ${arch} installs on ${arch} and then fails to load. Build the payload ` +
             `for ${arch}\n` +
-            '    (its own prebuild), or drop `--arch` and label the payload you actually have.');
+            '    (its own prebuild), or assemble the stage without `--arch` and label the payload you ' +
+            'actually have.');
     }
 }
 /** ELF, Mach-O (both endiannesses, both widths, and a fat archive) or PE. */

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

@@ -1,4 +1,4 @@
-import type { FormatDescriptor, ShipSettings, StagedFile } from './types.js';
+import type { FormatDescriptor, FormatId, ShipSettings, StagedFile } from './types.js';
 /** Everything the planner needs that it cannot derive from the settings alone. */
 export interface StageInputs {
     /** Paths inside `settings.bundleDir`, relative and POSIX-separated. */
@@ -24,8 +24,37 @@ export declare function planStage(settings: ShipSettings, inputs: StageInputs):
  * The per-format additions. Only the licence differs today, and it differs in
  * BOTH place and shape: Debian policy wants a machine-readable `copyright` in
  * `share/doc/<pkg>/`, RPM wants the licence text under `share/licenses/<pkg>/`.
+ *
+ * A project with no licence file is REFUSED here rather than packaged without
+ * one. Debian Policy § 12.5 makes the copyright file mandatory and lintian
+ * raises `no-copyright-file` as an error, but nothing between this function and
+ * the installed package says so: an empty overlay produced a `.deb` whose
+ * control file `dpkg-deb --info` prints cleanly, that `dpkg -i` installs, and
+ * that is simply unlicensed. That is what gjsify's own package was, every
+ * release of it, until the first CI leg that read one with a real `dpkg` said
+ * so on its eighth assertion.
+ *
+ * It throws on the host that can act on it. This runs during `--stage` as well
+ * as during a one-shot `ship`, so the refusal lands where the project — and the
+ * missing `LICENSE` — actually is; {@link assertOverlayIsLicensed} repeats it at
+ * pack time for a stage that arrived from somewhere else.
  */
 export declare function planOverlay(settings: ShipSettings, format: FormatDescriptor, inputs: StageInputs): StagedFile[];
+/**
+ * The same refusal, at pack time.
+ *
+ * `planOverlay` cannot cover `--from-stage`: that path never plans anything, it
+ * rehydrates the closure the assembling host wrote. A manifest whose
+ * `overlay.deb` is `[]` passes every structural check in `readStageManifest`
+ * — the key is present, the value is an array of the right shape — and the
+ * silent unlicensed package comes back. The stage manifest's own header lists
+ * "no `overlay`" among the omissions that fail at exit 0 with an artifact that
+ * installs; this is where that stops being a comment.
+ *
+ * Cheap enough to run on both paths, so it does, and a stage written by this
+ * version can no longer reach it.
+ */
+export declare function assertOverlayIsLicensed(formatId: FormatId, binaryName: string, overlay: readonly StagedFile[]): void;
 /**
  * The hicolor subdirectory for an icon: `scalable` for SVG, otherwise the
  * pixel size read from a `<n>x<n>` path component or a trailing number in the

package/lib/utils/ship/plan.js

@@ -2,6 +2,7 @@
 // case (including the ones that must be REFUSED) is unit-testable. Same split
 // as `utils/copy-targets.ts`, and for the same reason: a stager that discovers
 // its own inputs can only be tested by building a real project.
+import { renderMimePackage } from './mime.js';
 import { basename, extname, posix } from 'node:path';
 /**
  * Build the prefix-relative payload.
@@ -65,6 +66,16 @@ export function planStage(settings, inputs) {
             source: { kind: 'file', path: file },
         });
     }
+    // A shared-mime-info document, when the project DEFINES a type rather than only handling one.
+    // `share/mime/packages/` is shared between packages, so the app id is the filename for the same
+    // reason it is for the GSettings schema: a generic name collides with another package's file.
+    if (settings.mimeTypes.length > 0) {
+        files.push({
+            path: `share/mime/packages/${settings.appId}.xml`,
+            mode: 0o644,
+            source: { kind: 'text', text: renderMimePackage(settings.mimeTypes) },
+        });
+    }
     // Compiled gettext catalogues, layout preserved: `share/locale/<lang>/LC_MESSAGES/<domain>.mo`
     // is where `bindtextdomain` looks, and nowhere else.
     for (const locale of settings.localeFiles) {
@@ -83,15 +94,56 @@ export function planStage(settings, inputs) {
  * The per-format additions. Only the licence differs today, and it differs in
  * BOTH place and shape: Debian policy wants a machine-readable `copyright` in
  * `share/doc/<pkg>/`, RPM wants the licence text under `share/licenses/<pkg>/`.
+ *
+ * A project with no licence file is REFUSED here rather than packaged without
+ * one. Debian Policy § 12.5 makes the copyright file mandatory and lintian
+ * raises `no-copyright-file` as an error, but nothing between this function and
+ * the installed package says so: an empty overlay produced a `.deb` whose
+ * control file `dpkg-deb --info` prints cleanly, that `dpkg -i` installs, and
+ * that is simply unlicensed. That is what gjsify's own package was, every
+ * release of it, until the first CI leg that read one with a real `dpkg` said
+ * so on its eighth assertion.
+ *
+ * It throws on the host that can act on it. This runs during `--stage` as well
+ * as during a one-shot `ship`, so the refusal lands where the project — and the
+ * missing `LICENSE` — actually is; {@link assertOverlayIsLicensed} repeats it at
+ * pack time for a stage that arrived from somewhere else.
  */
 export function planOverlay(settings, format, inputs) {
-    if (inputs.licenseText === undefined)
-        return [];
+    if (inputs.licenseText === undefined) {
+        throw new Error(`gjsify ship: no licence file found, so the ${format.id} package would ship no ` +
+            `${format.licenseDest(settings.binaryName)}. Debian Policy § 12.5 requires it and lintian ` +
+            'errors without it, and neither dpkg nor rpm will tell you it is missing. Add a LICENSE file ' +
+            `to ${settings.projectDir} or to the root of its repository, or point ` +
+            '`gjsify.ship.licenseFile` at the one this package ships under.');
+    }
     const text = format.licenseKind === 'debian-copyright'
         ? renderDebianCopyright(settings, inputs.licenseText)
         : inputs.licenseText;
     return [{ path: format.licenseDest(settings.binaryName), mode: 0o644, source: { kind: 'text', text } }];
 }
+/**
+ * The same refusal, at pack time.
+ *
+ * `planOverlay` cannot cover `--from-stage`: that path never plans anything, it
+ * rehydrates the closure the assembling host wrote. A manifest whose
+ * `overlay.deb` is `[]` passes every structural check in `readStageManifest`
+ * — the key is present, the value is an array of the right shape — and the
+ * silent unlicensed package comes back. The stage manifest's own header lists
+ * "no `overlay`" among the omissions that fail at exit 0 with an artifact that
+ * installs; this is where that stops being a comment.
+ *
+ * Cheap enough to run on both paths, so it does, and a stage written by this
+ * version can no longer reach it.
+ */
+export function assertOverlayIsLicensed(formatId, binaryName, overlay) {
+    if (overlay.length > 0)
+        return;
+    throw new Error(`gjsify ship: this stage carries no ${formatId} licence overlay, so the package would ship no ` +
+        `licence file for ${binaryName} — Debian Policy § 12.5 requires one and lintian errors without ` +
+        'it. The fix is on the assembling host, not this one: give that project a LICENSE (or set ' +
+        '`gjsify.ship.licenseFile`) and re-run the `--stage` phase.');
+}
 /**
  * Debian machine-readable copyright, format 1.0. The licence text is indented
  * by one space and its blank lines become ` .` — a bare blank line ends the

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

@@ -1,7 +1,7 @@
-import type { PayloadEntry } from './payload.js';
-import type { ShipSettings } from './types.js';
+import { type PayloadEntry } from './payload.js';
+import type { PackSettings } from './types.js';
 export interface RpmInputs {
-    settings: ShipSettings;
+    settings: PackSettings;
     payload: readonly PayloadEntry[];
     prefix: string;
     depends: readonly string[];

package/lib/utils/ship/rpm.js

@@ -15,6 +15,7 @@ import { createHash } from 'node:crypto';
 import { concatBytes } from './bytes.js';
 import { createCpioArchive, S_IFDIR, S_IFREG } from './cpio.js';
 import { parseDepend } from './depends.js';
+import { readPayloadFacts, readShebangInterpreters } from './payload.js';
 import { buildRpmHeader, buildRpmLead, padToEight, RpmType, RPM_TAG_HEADERIMMUTABLE, RPM_TAG_HEADERSIGNATURES, } from './rpm-header.js';
 import { gzipDeterministic } from './gzip.js';
 import { renderRpmScriptlets } from './scripts.js';
@@ -80,6 +81,9 @@ const SENSE = {
     INTERP: 1 << 8,
     SCRIPT_POST: 1 << 10,
     SCRIPT_POSTUN: 1 << 12,
+    // "This one was derived from the payload, not declared by the packager" —
+    // the sense `rpmbuild`'s own dependency generator uses (measured: 16384).
+    FIND_REQUIRES: 1 << 14,
     RPMLIB: 1 << 24,
 };
 /** SHA-256 in rpm's digest-algorithm numbering (PGP hash algorithm ids). */
@@ -205,8 +209,9 @@ function mainHeaderEntries(inputs, files, cpio, compressed) {
         dirIndexes.push(index);
         baseNames.push(file.path.slice(slash + 1));
     }
-    const scripts = renderRpmScriptlets(settings, inputs.prefix);
-    const requires = buildRequires(inputs.depends, scripts);
+    // From the PAYLOAD, not the settings — see the same call in `deb.ts`.
+    const scripts = renderRpmScriptlets(readPayloadFacts(inputs.payload), inputs.prefix);
+    const requires = buildRequires(inputs.depends, scripts, readShebangInterpreters(inputs.payload));
     const entries = [
         { tag: TAG.HEADERI18NTABLE, type: RpmType.STRING_ARRAY, value: ['C'] },
         { tag: TAG.NAME, type: RpmType.STRING, value: settings.binaryName },
@@ -325,8 +330,15 @@ function assertParallelFileArrays(entries, fileCount) {
  * A scriptlet's interpreter is a dependency like any other and rpm expects it
  * declared with the matching `SCRIPT_*` sense bit — without it, a system
  * without `/bin/sh` installs the package and then fails inside `%post`.
+ *
+ * The payload's own executables need the same treatment, and until the first
+ * real `rpm -qp --requires` ran against this writer nothing here said so: every
+ * `.rpm` it produced installed a `#!/bin/sh` launcher and declared no shell.
+ * The two senses are not redundant and rpm emits both — a package can need a
+ * shell to CONFIGURE (`Requires(post)`) and to RUN (a plain requirement), and
+ * dropping either is a different broken system.
  */
-function buildRequires(depends, scripts) {
+function buildRequires(depends, scripts, interpreters) {
     const names = [];
     const flags = [];
     const versions = [];
@@ -346,6 +358,11 @@ function buildRequires(depends, scripts) {
         flags.push(SENSE.INTERP | SENSE.SCRIPT_POSTUN);
         versions.push('');
     }
+    for (const interpreter of interpreters) {
+        names.push(interpreter);
+        flags.push(SENSE.FIND_REQUIRES);
+        versions.push('');
+    }
     for (const [name, version] of RPMLIB_REQUIRES) {
         names.push(name);
         flags.push(SENSE.RPMLIB | SENSE.LESS | SENSE.EQUAL);