@gjsify/cli 0.46.0 → 0.48.0

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

@@ -53,8 +53,17 @@ export declare const STAGE_MANIFEST_FILE = ".gjsify-ship-stage.json";
  *    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".
+ *
+ * 6 made an overlay entry carry EITHER `text` or `base64`, for the gzipped
+ * `changelog.Debian.gz` Debian Policy § 4.4 requires. That is the meaning case
+ * again and the sharpest one yet: a schema-5 reader demands `text` on every
+ * entry, so it meets a 6 stage and fails on `overlay.deb[1].text must be a
+ * string` — a sentence about a field, over a stage whose only problem is the
+ * gjsify reading it. And the inverse is worse than a bad message: a reader that
+ * ignored the unknown key would write an entry with no bytes, or write base64 AS
+ * text, and ship a `.deb` whose changelog is a wall of ASCII at exit 0.
  */
-export declare const STAGE_SCHEMA_VERSION = 5;
+export declare const STAGE_SCHEMA_VERSION = 6;
 /** What this stage was assembled FOR, in the repo-wide `${process.platform}-${process.arch}` spelling. */
 export interface StageTarget {
     /** The layout the stage carries, in the `process.platform` spelling — `win32`, never `windows`. */
@@ -65,9 +74,19 @@ export interface StageTarget {
 export interface StageFileRecord extends StagedMode {
     bytes: number;
 }
-/** One pre-rendered overlay file. Text only — see {@link writeStageManifest}. */
+/**
+ * One pre-rendered overlay file. EXACTLY ONE of `text` and `base64` is present —
+ * see {@link writeStageManifest} for why a file reference is still refused.
+ *
+ * `text` is preferred wherever the content is text, because the sidecar is the one
+ * artifact in this handoff a human reads: the whole copyright is legible in it. The
+ * `base64` half exists for the gzipped Debian changelog, whose bytes must be the
+ * bytes that ship — a stage packed on another host cannot re-compress it and get
+ * the same file.
+ */
 export interface StageOverlayFile extends StagedMode {
-    text: string;
+    text?: string;
+    base64?: string;
 }
 export interface StageManifest {
     schema: number;

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

@@ -13,8 +13,10 @@
 //   * no `staged` — modes come from the plan (see `stage-writer.ts`), so the
 //     launcher packs 0644 and the installed `bin/<name>` is not executable.
 //   * no `overlay` — the `.deb` ships no `/usr/share/doc/<pkg>/copyright`,
-//     which Debian Policy § 12.5 requires and lintian errors on, and the
-//     `.rpm` ships no `/usr/share/licenses/<pkg>/LICENSE`.
+//     which Debian Policy § 12.5 requires and lintian errors on, no
+//     `/usr/share/doc/<pkg>/changelog.Debian.gz`, which § 4.4 requires and
+//     lintian also errors on, and the `.rpm` ships no
+//     `/usr/share/licenses/<pkg>/LICENSE`.
 //   * no `namespaces` — they are scanned from the BUILD TREE's bundle, so a
 //     packing host that re-derived nothing would emit `Depends:` without
 //     `gir1.2-gtk-4.0` and `gir1.2-adw-1`: the package installs on a machine
@@ -36,6 +38,7 @@
 //     that is right there.
 import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { join, sep } from 'node:path';
+import { base64Decode, base64Encode } from '../base64.js';
 import { cliVersion } from '../publish-headers.js';
 import { FORMAT_IDS } from './formats.js';
 import { layoutForOs, LAYOUTS, LAYOUT_NAMES } from './layout.js';
@@ -93,8 +96,17 @@ export const STAGE_MANIFEST_FILE = '.gjsify-ship-stage.json';
  *    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".
+ *
+ * 6 made an overlay entry carry EITHER `text` or `base64`, for the gzipped
+ * `changelog.Debian.gz` Debian Policy § 4.4 requires. That is the meaning case
+ * again and the sharpest one yet: a schema-5 reader demands `text` on every
+ * entry, so it meets a 6 stage and fails on `overlay.deb[1].text must be a
+ * string` — a sentence about a field, over a stage whose only problem is the
+ * gjsify reading it. And the inverse is worse than a bad message: a reader that
+ * ignored the unknown key would write an entry with no bytes, or write base64 AS
+ * text, and ship a `.deb` whose changelog is a wall of ASCII at exit 0.
  */
-export const STAGE_SCHEMA_VERSION = 5;
+export const STAGE_SCHEMA_VERSION = 6;
 /**
  * The half of {@link ShipSettings} that crosses the host boundary.
  *
@@ -149,15 +161,17 @@ export function writeStageManifest(input) {
     const overlay = {};
     for (const format of input.formats) {
         overlay[format.id] = (input.overlay.get(format.id) ?? []).map((file) => {
-            if (file.source.kind !== 'text') {
-                // Every overlay entry `planOverlay` produces today is rendered text. A file
-                // reference would be a build-host path, and putting one in here is how the
-                // manifest would start naming files the packing host cannot open.
-                throw new Error(`gjsify ship: internal error — the ${format.id} overlay entry ${file.path} is a file ` +
-                    'reference, and a stage manifest may only carry rendered text. Render it in ' +
-                    '`planOverlay` instead.');
+            if (file.source.kind === 'text')
+                return { path: file.path, mode: file.mode, text: file.source.text };
+            if (file.source.kind === 'bytes') {
+                return { path: file.path, mode: file.mode, base64: base64Encode(file.source.data) };
             }
-            return { path: file.path, mode: file.mode, text: file.source.text };
+            // A FILE reference is still refused. It would be a build-host path, and
+            // putting one in here is how the manifest would start naming files the
+            // packing host cannot open — the failure the closure exists to prevent.
+            throw new Error(`gjsify ship: internal error — the ${format.id} overlay entry ${file.path} is a file ` +
+                'reference, and a stage manifest may only carry rendered bytes. Render it in ' +
+                '`planOverlay` instead.');
         });
     }
     const manifest = {
@@ -295,10 +309,21 @@ export function readStageManifest(stageDir) {
         // lintian errors on.
         manifest.overlay[id] = expectArray(overlay[id], at(`overlay.${id}`)).map((entry, index) => {
             const file = record(entry, at(`overlay.${id}[${index}]`));
+            const where = at(`overlay.${id}[${index}]`);
+            // EXACTLY ONE, checked in both directions. Neither would write an empty
+            // file at a path Debian policy demands content at; both would leave which
+            // one wins to whichever branch `overlayFiles` happens to test first.
+            if ((file.text === undefined) === (file.base64 === undefined)) {
+                throw new Error(`gjsify ship: ${where} must carry exactly one of \`text\` and \`base64\`. ` +
+                    'An overlay entry is either rendered text or rendered bytes; an entry with ' +
+                    'neither would pack an empty file at a path the format requires content at.');
+            }
             return {
                 path: expectString(file.path, at(`overlay.${id}[${index}].path`)),
                 mode: expectInteger(file.mode, at(`overlay.${id}[${index}].mode`)),
-                text: expectString(file.text, at(`overlay.${id}[${index}].text`)),
+                ...(file.text === undefined
+                    ? { base64: expectString(file.base64, at(`overlay.${id}[${index}].base64`)) }
+                    : { text: expectString(file.text, at(`overlay.${id}[${index}].text`)) }),
             };
         });
     }
@@ -329,7 +354,9 @@ export function overlayFiles(manifest, format) {
     return (manifest.overlay[format] ?? []).map((file) => ({
         path: file.path,
         mode: file.mode,
-        source: { kind: 'text', text: file.text },
+        source: file.base64 === undefined
+            ? { kind: 'text', text: file.text ?? '' }
+            : { kind: 'bytes', data: base64Decode(file.base64) },
     }));
 }
 /**

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

@@ -224,6 +224,17 @@ export interface FormatDescriptor {
     interpreterGap: string;
     /** Where the project's licence text goes in this format's overlay. */
     licenseDest: (binaryName: string) => string;
+    /**
+     * Where this format wants a packaging changelog, when it wants one at all.
+     *
+     * OPTIONAL, unlike {@link licenseDest}, and the asymmetry is a policy
+     * difference rather than an oversight: Debian Policy § 4.4 makes
+     * `share/doc/<package>/changelog.Debian.gz` mandatory and lintian errors
+     * without it, while rpm's `%doc` changelog is a convention and `rpm` says
+     * nothing when it is absent. A format that leaves this undefined has
+     * answered "this format does not require one".
+     */
+    changelogDest?: (binaryName: string) => string;
     /**
      * `debian-copyright` renders the machine-readable copyright 1.0 format
      * Debian policy asks for; `plain` copies the licence file verbatim.
@@ -420,6 +431,8 @@ export interface ShipSettings extends PackSettings {
     projectDir: string;
     /** Absolute path to the licence file, when one was found. */
     licenseFile?: string;
+    /** Absolute path to the project's own changelog, when one was found. */
+    changelogFile?: string;
     /** `'app'` stages a desktop entry and an icon; `'cli'` stages neither. */
     kind: 'app' | 'cli';
     /** Absolute path to the built bundle that `bin/<binaryName>` executes. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.46.0",
+    "version": "0.48.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -142,21 +142,21 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.46.0",
-        "@gjsify/create-app": "^0.46.0",
-        "@gjsify/node-globals": "^0.46.0",
-        "@gjsify/node-polyfills": "^0.46.0",
-        "@gjsify/npm-registry": "^0.46.0",
-        "@gjsify/resolve-npm": "^0.46.0",
-        "@gjsify/rolldown-plugin-gjsify": "^0.46.0",
-        "@gjsify/vite-plugin-blueprint": "^0.46.0",
-        "@gjsify/rolldown-plugin-pnp": "^0.46.0",
-        "@gjsify/semver": "^0.46.0",
-        "@gjsify/tar": "^0.46.0",
-        "@gjsify/tsc": "^0.46.0",
-        "@gjsify/utils": "^0.46.0",
-        "@gjsify/web-polyfills": "^0.46.0",
-        "@gjsify/workspace": "^0.46.0",
+        "@gjsify/buffer": "^0.48.0",
+        "@gjsify/create-app": "^0.48.0",
+        "@gjsify/node-globals": "^0.48.0",
+        "@gjsify/node-polyfills": "^0.48.0",
+        "@gjsify/npm-registry": "^0.48.0",
+        "@gjsify/resolve-npm": "^0.48.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.48.0",
+        "@gjsify/vite-plugin-blueprint": "^0.48.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.48.0",
+        "@gjsify/semver": "^0.48.0",
+        "@gjsify/tar": "^0.48.0",
+        "@gjsify/tsc": "^0.48.0",
+        "@gjsify/utils": "^0.48.0",
+        "@gjsify/web-polyfills": "^0.48.0",
+        "@gjsify/workspace": "^0.48.0",
         "acorn": "^8.17.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
@@ -165,13 +165,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.46.0",
+        "@gjsify/unit": "^0.48.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.46.0",
-        "@gjsify/rolldown-native": "^0.46.0"
+        "@gjsify/oxfmt-native": "^0.48.0",
+        "@gjsify/rolldown-native": "^0.48.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {