@gjsify/cli 0.46.0 → 0.48.0

package/lib/utils/publish-readback.js

@@ -0,0 +1,273 @@
+// Post-PUT read-back for `gjsify publish`: does the registry actually RESOLVE
+// the version we just uploaded?
+//
+// THE INCIDENT (v0.46.0, run 33735989472). The job `Publish
+// @gjsify/node-runtime-darwin-arm64 (bundled Node)` reported SUCCESS and
+// published NOTHING. Its own log, with GJSIFY_PUBLISH_DEBUG=1:
+//
+//     gjsify publish: PUT https://registry.npmjs.org/@gjsify%2fnode-runtime-darwin-arm64
+//       payload size:  53863410 bytes
+//     + @gjsify/node-runtime-darwin-arm64@0.46.0
+//
+// The job was green. Minutes later the registry had NEITHER half: the version
+// endpoint 404'd, the tarball URL 404'd, `npm view … version` still answered
+// 0.45.0, and the packument's `time` map had no 0.46.0 entry at all. Only a
+// manual single-job rerun made it land (registry time 09:49:07.419Z). Payload
+// size was NOT the cause — darwin-x64 at 55189094 bytes, i.e. LARGER, published
+// fine in the same rerun. `res.ok` was checked and npm's answer really was 2xx,
+// so the plain `+` success path is exactly what the code was written to print.
+//
+// WHAT THE 2xx MEANS, MEASURED. A 2xx from npm is an ACCEPTED write, not a
+// durable one. Correlating all 199 `+ <name>@0.46.0` lines of that release's
+// serial sweep with each packument's own `time["0.46.0"]`:
+//
+//   180 / 199 (90.5%)  registry time is 0.4-2.4 s BEFORE our success line (median
+//                      0.6 s) — the version doc existed before the response came back
+//    19 / 199  (9.5%)  registry time is 56.2 s - 251.7 s AFTER the 2xx; the
+//                      extreme is @gjsify/child_process, PUT 09:25:08.7, `+`
+//                      printed 09:25:10.3, registry time 09:29:21.996Z
+//                      (+4m11s). THREE of the 19 were recorded after the
+//                      publish job's own completed_at (09:28:35Z).
+//     1              not recorded until a manual rerun — the incident above.
+//
+// So "not there" and "not there YET" are the same observation for up to ~4.2
+// minutes, and no client-side signal separates them. That is what this module
+// is for: it turns "npm said 2xx" into "the registry serves it", and when it
+// cannot, it says which of the two it saw and for how long it looked.
+//
+// THE MECHANISM, and why the lag is a WRITE and not a read cache. `dist.signatures`
+// correlates 1:1 with the sign of that lag across all 199: every one of the 19
+// late packages carries TWO signatures (same keyid, different sig), every one of
+// the 180 carries ONE, and the client sent exactly one PUT per package (199
+// distinct names, no retry, no 5xx in the log). So the late version document was
+// written a second time server-side, and `time[version]` records that second
+// write. Corroborated client-side rather than inferred: @gjsify/child_process's
+// +251.7 s is exactly the package that failed all three attempt-1 node-runtime
+// jobs at 09:29:05 with `ETARGET / No matching version found for
+// @gjsify/child_process@^0.46.0` — 15 s BEFORE its recorded time and 4 min after
+// its `+`. A lag of this kind therefore does not merely delay a report; it
+// cascades into every job that installs the release.
+//
+// WHY THE PACKUMENT AND NOT THE TARBALL URL. One abbreviated-packument GET
+// answers both halves that #1407 split apart (npm had stored the tarball and no
+// packument there): the version record carries `dist.tarball`, so its presence
+// is checked from the same response with no second request. It proves the
+// registry ADVERTISES a tarball, not that the bytes are fetchable — a HEAD on
+// the tarball would be a second round trip per package and is deliberately not
+// done here. Same oracle and same headers as
+// `scripts/verify-published-closure.mjs`, so the per-package check and the
+// end-of-release closure check cannot disagree about what "published" means —
+// an equality that had to be MADE: the closure probe asked for the version key
+// alone, so the tarball half of every publish the sweep defers to it was checked
+// by nothing. It now reads `dist.tarball` from the same document.
+import { escapePackageName } from './publish-headers.js';
+/**
+ * Backoff between probes, in ms; the last value repeats until the budget is out.
+ *
+ * Shaped by the distribution in the header, not picked for roundness: 90.5% of
+ * writes are already committed when the 2xx arrives, so the FIRST probe is
+ * immediate and costs one ~0.5 s GET for nine packages in ten. The tail is
+ * minutes long and coarse, so probing it finely would only add requests — after
+ * 30 s the interval stops shrinking.
+ */
+const BACKOFF_MS = [2_000, 4_000, 8_000, 15_000, 30_000];
+/** Delay before probe `round + 2`. Past the table's end the last value repeats. */
+export function backoffFor(round) {
+    return BACKOFF_MS[Math.min(Math.max(round, 0), BACKOFF_MS.length - 1)] ?? 30_000;
+}
+/**
+ * The smallest request timeout a probe is ever given.
+ *
+ * A probe cut below the time an answer takes reports `error` — "we do not know" —
+ * where it would have read a 404, so the decisive LAST probe of a short budget
+ * would lose the verdict the whole read-back exists to produce. Measured against
+ * registry.npmjs.org from a European workstation, 21 abbreviated-packument GETs
+ * ran 0.48-0.62 s (median 0.57), so 2 s is ~3.5x the median and above every
+ * observation — the floor is what lets a probe answer, not a guess at latency.
+ */
+const MIN_PROBE_TIMEOUT_MS = 2_000;
+/**
+ * A probe's request timeout: what was configured, never more than the budget has
+ * left to spend — but never less than a probe needs to answer.
+ *
+ * Configured and budget are otherwise independent, and that makes
+ * `--verify-timeout 5` — what the 199-package sweep passes — a promise the code
+ * does not keep: one unanswered request may block for the 30 s default, six times
+ * the budget it was given, and 199 of those cost ~100 min against the ~11% the
+ * deferral is argued on. Clamping bounds the wall clock at
+ * `budget + MIN_PROBE_TIMEOUT_MS` instead. The floor is the other half of the
+ * same honesty: clamping all the way to zero traded a 30 s overshoot for an
+ * `error` verdict on a probe that was about to return the 404 (measured — it
+ * turned the incident's own e2e row from `absent: 404` into `request failed
+ * (This operation was aborted)`).
+ */
+export function probeTimeoutFor(configuredMs, remainingMs) {
+    return Math.min(configuredMs, Math.max(remainingMs, MIN_PROBE_TIMEOUT_MS));
+}
+/**
+ * Default polling budget: 300 s.
+ *
+ * The measured maximum lag between a 2xx and the registry recording the version
+ * was 251.7 s (@gjsify/child_process, v0.46.0), so a budget below ~4.2 minutes
+ * turns npm's normal queueing into a false red — and a false red at release time
+ * costs a manual re-run of a workflow that did its job. 300 s clears that
+ * maximum and is still short enough that a genuinely lost write is reported by
+ * the job that lost it rather than by a later sweep.
+ *
+ * THAT MAXIMUM IS A SAMPLE MAXIMUM, and the sample does not look truncated by
+ * nature. The 19 lags fall in buckets ~20-30 s apart — 56(2), 76(3), 96(3),
+ * 127(4), 157(3), 189(1), 251(3) — and the TOP bucket is as populated as the
+ * middle ones, which is the shape of a distribution cut off by the observation
+ * rather than one decaying to zero. One release is one sample, so a lag past
+ * 300 s is not ruled out; what makes 300 s affordable anyway is that the
+ * remediation is verified rather than assumed. The re-run this reports lands on
+ * the 409 path, and that path READS BACK too (see the conflict branch in
+ * `commands/publish.ts`), so a window that turns out to be too short costs one
+ * re-run that confirms — it does not hand back an unverified success.
+ */
+export const DEFAULT_VERIFY_BUDGET_MS = 300_000;
+/**
+ * Poll the registry until `name@version` resolves, or the budget runs out.
+ *
+ * No side effects, no exits, no printing beyond the injected `log` — the caller
+ * owns presentation, same contract as {@link import('./publish-diagnose.js')}.
+ */
+export async function verifyPublishedVersion(input) {
+    const { registry, name, version, budgetMs } = input;
+    const doFetch = input.fetchImpl ?? ((...args) => globalThis.fetch(...args));
+    const sleep = input.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = input.now ?? (() => Date.now());
+    const probeTimeoutMs = input.probeTimeoutMs ?? 30_000;
+    const registryClean = registry.endsWith('/') ? registry.slice(0, -1) : registry;
+    const url = `${registryClean}/${escapePackageName(name)}`;
+    const started = now();
+    let attempts = 0;
+    let last = { state: 'error', detail: 'no probe was sent' };
+    for (let round = 0;; round++) {
+        attempts++;
+        last = await probeOnce({
+            url,
+            version,
+            doFetch,
+            probeTimeoutMs: probeTimeoutFor(probeTimeoutMs, budgetMs - (now() - started)),
+            authorization: input.authorization,
+        });
+        input.log?.(`gjsify publish: read-back probe ${attempts} of ${name}@${version} → ${last.state}` +
+            (last.state === 'present' ? '' : ` (${last.detail})`));
+        if (last.state === 'present')
+            break;
+        const remaining = budgetMs - (now() - started);
+        if (remaining <= 0)
+            break;
+        await sleep(Math.min(backoffFor(round), remaining));
+    }
+    return { confirmed: last.state === 'present', attempts, elapsedMs: now() - started, url, last };
+}
+async function probeOnce(input) {
+    const { url, version, doFetch, probeTimeoutMs } = input;
+    // `AbortController` + a timer rather than `AbortSignal.timeout`, which the
+    // CLI does not use anywhere and which this file must not be the first to
+    // require of a GJS host.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), probeTimeoutMs);
+    let res;
+    try {
+        res = await doFetch(url, {
+            headers: {
+                // Abbreviated packument: version keys + `dist`, a fraction of the
+                // bytes of the full document. `no-cache` because a CDN edge will
+                // otherwise answer with a document minted BEFORE the publish we
+                // are asking about — which is the whole question here.
+                accept: 'application/vnd.npm.install-v1+json',
+                'cache-control': 'no-cache',
+                ...(input.authorization ? { authorization: input.authorization } : {}),
+            },
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        // A real throw path: network failure, DNS, or our own abort above.
+        const msg = err instanceof Error ? err.message : String(err);
+        return { state: 'error', detail: `request failed (${msg})` };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (res.status === 404) {
+        return { state: 'absent', status: 404, detail: '404 — the registry serves no packument for this name' };
+    }
+    if (!res.ok) {
+        return { state: 'error', status: res.status, detail: `${res.status} ${res.statusText}` };
+    }
+    let doc;
+    try {
+        doc = await res.json();
+    }
+    catch (err) {
+        // A 200 whose body is not a packument answers nothing; `absent` would be
+        // a verdict we did not earn.
+        const msg = err instanceof Error ? err.message : String(err);
+        return { state: 'error', status: res.status, detail: `packument is not JSON (${msg})` };
+    }
+    const versions = doc?.versions;
+    const known = versions && typeof versions === 'object' ? Object.keys(versions) : [];
+    const entry = versions && typeof versions === 'object' ? versions[version] : undefined;
+    if (!entry) {
+        const newest = known.length > 0 ? known[known.length - 1] : '(none)';
+        return {
+            state: 'absent',
+            status: res.status,
+            detail: `packument carries ${known.length} version(s), newest ${newest} — ${version} is not among them`,
+        };
+    }
+    const tarball = entry.dist?.tarball;
+    if (typeof tarball !== 'string' || tarball.length === 0) {
+        // The #1407 half: a version record with no tarball to install.
+        return {
+            state: 'absent',
+            status: res.status,
+            detail: `packument has ${version} but its \`dist.tarball\` is missing`,
+        };
+    }
+    return { state: 'present', status: res.status, tarball };
+}
+/**
+ * The unconfirmed-publish diagnostic, ready for stderr.
+ *
+ * The message has to answer three questions the incident log could not, which is
+ * why it needed the registry to reconstruct at all: what was PUT, what was asked,
+ * and what came back.
+ */
+export function formatUnconfirmedPublish(opts) {
+    const { name, version, putUrl, putStatus, putStatusText, payloadBytes, readback } = opts;
+    const claim = opts.claim ?? 'accepted';
+    const seconds = (readback.elapsedMs / 1000).toFixed(1);
+    // Only ever called on an UNCONFIRMED read-back, so `last` is `absent` or
+    // `error` — both carry a `detail`; `present` has nothing to explain.
+    const answered = readback.last.state === 'present' ? 'served' : readback.last.detail;
+    const headline = claim === 'already-published'
+        ? `npm says ${version} is ALREADY PUBLISHED but the registry does not serve it.`
+        : 'npm ACCEPTED the upload but the registry does not serve it.';
+    const remedy = claim === 'already-published'
+        ? [
+            '  A 409 is npm refusing to overwrite a version it holds, which is not the same as serving it: in',
+            '  the v0.46.0 recovery @gjsify/node-runtime-darwin-arm64 was answered 409 at 09:48:49 and the',
+            '  registry recorded 0.46.0 at 09:49:07, 18s later. Re-running answers the same 409, so it cannot',
+            '  fix this — wait and re-read (`npm view <name>@<version>`), or check https://status.npmjs.org/.',
+        ]
+        : [
+            '  A 2xx from npm is an ACCEPTED write, not a durable one. In the v0.46.0 release 19 of 199',
+            '  packages were recorded by the registry 56-252s after their 2xx, and ONE was never recorded',
+            '  at all while its job stayed green — that is the failure this check exists to name.',
+            `  Re-run this publish (\`--tolerate-republish\` no-ops if it landed meanwhile). If it keeps`,
+            '  failing, the write was rejected downstream of the 2xx: check https://status.npmjs.org/.',
+        ];
+    return [
+        `gjsify publish: ${name}@${version} — ${headline}`,
+        `  PUT       ${putUrl} (${payloadBytes} bytes) → ${putStatus} ${putStatusText}`,
+        `  read-back GET ${readback.url} (accept: application/vnd.npm.install-v1+json, cache-control: no-cache)`,
+        `  answered  ${readback.last.state}: ${answered}`,
+        `            after ${readback.attempts} probe(s) over ${seconds}s`,
+        ...remedy,
+    ].join('\n');
+}

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

@@ -0,0 +1,56 @@
+import type { PackSettings } from './types.js';
+/**
+ * `Thu, 04 Sep 2026 12:34:56 +0000` — the trailer format Policy § 4.4 requires.
+ *
+ * Always UTC, and the offset is written out rather than derived: the build stamp is
+ * Unix seconds, so there is no zone to preserve, and a package built in two places
+ * must not differ by a timezone.
+ *
+ * @param unixSeconds the build stamp every header in the artifact shares
+ */
+export declare function rfc822(unixSeconds: number): string;
+/**
+ * The bullet lines a project's own changelog carries for ONE version.
+ *
+ * Reads the Markdown release-note shape `release-it`'s conventional-changelog
+ * preset writes — `## [0.47.0](compare-url) (2026-09-03)`, or a bare `## 0.47.0`
+ * for a first release — and takes the `*`/`-` bullets under it up to the next
+ * version heading. Category subheadings (`### Bug Fixes`) are dropped: a Debian
+ * change block is a flat list, and a heading rendered as a bullet reads as a change
+ * that was made.
+ *
+ * Markdown links collapse to their text (`[#1510](https://…)` → `#1510`) and bold
+ * scopes lose their asterisks, because the destination is plain text that `apt
+ * changelog` prints to a terminal.
+ *
+ * @returns one string per bullet, empty when the file does not name this version
+ */
+export declare function changelogEntriesFor(version: string, source: string): string[];
+/**
+ * The whole `changelog.Debian` file: one entry, for the version being packaged.
+ *
+ * `unstable` is the distribution and `medium` the urgency — the values `dh_make`
+ * seeds a package with, and the only honest ones for an artifact built outside any
+ * Debian suite: this package targets no release, and claiming one would put a
+ * specific false statement in a field `apt` reads.
+ *
+ * The trailer's spacing is load-bearing and is the usual way this file is got
+ * wrong: exactly one leading space, then `--`, one space, the maintainer, and TWO
+ * spaces before the date.
+ *
+ * TWO lintian tags this file still raises, both measured on lintian 2.117 against
+ * gjsify's own `.deb` and both left alone deliberately:
+ *
+ *  - `initial-upload-closes-no-bugs`, because the Debian revision is `-1` and the
+ *    entry closes no bug. It is a statement about the Debian ARCHIVE's ITP
+ *    workflow — the first upload of a new source package should close its ITP bug
+ *    — and a package built by `gjsify ship` is never uploaded there. There is no
+ *    bug number that would be true to write, so the tag is inapplicable rather
+ *    than unmet.
+ *  - `changelog-not-compressed-with-max-compression`. Policy asks for `gzip -9`
+ *    and neither `CompressionStream` nor `@gjsify/zlib` takes a level, so
+ *    `gzipDeterministic` cannot ask for one. Ledgered in `status/open-todos.md`:
+ *    the fix is a capability in the core, and stamping the header's XFL byte to
+ *    claim max compression we did not use is not one.
+ */
+export declare function renderDebianChangelog(settings: PackSettings, source: string | undefined, mtime: number): string;

package/lib/utils/ship/changelog.js

@@ -0,0 +1,166 @@
+// `/usr/share/doc/<package>/changelog.Debian.gz` — Debian Policy § 4.4.
+//
+// WHY IT EXISTS AT ALL. Every `.deb` this writer produced shipped without one,
+// which the first real lintian this project ever ran named as the only
+// error-severity tag left once the copyright landed:
+//
+//   E: gjsify: no-changelog usr/share/doc/gjsify/changelog.Debian.gz (non-native package)
+//
+// "non-native" is not a coincidence: `deb.ts` writes `Version: <version>-<release>`,
+// and a version carrying a Debian revision is by definition a non-native package,
+// whose changelog is `changelog.Debian.gz` rather than `changelog.gz`.
+//
+// WHAT THE ENTRY SAYS — the open question the ledger left, decided here.
+//
+// ONE ENTRY, for the version being packaged, and that is not a truncation. Policy
+// § 4.4's file is the DEBIAN changelog: it records the packaging, not upstream's
+// development. `gjsify ship` performs exactly one packaging event per version, so
+// one entry is the whole history there is to tell. The upstream history has its own
+// (optional) file, `changelog.gz`, and this writer does not claim to produce it.
+//
+// The BODY comes from the project's own changelog when one is found — `CHANGELOG.md`
+// beside the project or up at its repository root, the same search the licence uses,
+// overridable with `gjsify.ship.changelogFile`. That was the choice worth making:
+// the GitHub release body says the same thing and is not reachable from a packing
+// host that may be offline (ADR 0024 § A2), while `CHANGELOG.md` is in the tree the
+// stage is assembled from. When nothing there names this version, the entry says so
+// in one line rather than inventing content.
+//
+// AND ONLY THE PACKAGED VERSION GETS A DATE. A Debian entry needs a distribution, an
+// urgency and an RFC822 timestamp; this writer has a real timestamp for exactly one
+// of them — `mtime`, the build stamp every other header in the artifact already
+// shares. Rendering the older versions would mean stamping each with a fabricated
+// time, since `CHANGELOG.md` dates them to the DAY, and a Debian changelog is read
+// by tools that compare those stamps.
+//
+// Deterministic by construction: the date is the build stamp, and the month and day
+// names are spelled out here rather than taken from `toLocaleString`, which answers
+// in the host's locale.
+const DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+/**
+ * `Thu, 04 Sep 2026 12:34:56 +0000` — the trailer format Policy § 4.4 requires.
+ *
+ * Always UTC, and the offset is written out rather than derived: the build stamp is
+ * Unix seconds, so there is no zone to preserve, and a package built in two places
+ * must not differ by a timezone.
+ *
+ * @param unixSeconds the build stamp every header in the artifact shares
+ */
+export function rfc822(unixSeconds) {
+    const at = new Date(unixSeconds * 1000);
+    const pad = (n) => String(n).padStart(2, '0');
+    return (`${DAYS[at.getUTCDay()]}, ${pad(at.getUTCDate())} ${MONTHS[at.getUTCMonth()]} ${at.getUTCFullYear()} ` +
+        `${pad(at.getUTCHours())}:${pad(at.getUTCMinutes())}:${pad(at.getUTCSeconds())} +0000`);
+}
+/**
+ * The bullet lines a project's own changelog carries for ONE version.
+ *
+ * Reads the Markdown release-note shape `release-it`'s conventional-changelog
+ * preset writes — `## [0.47.0](compare-url) (2026-09-03)`, or a bare `## 0.47.0`
+ * for a first release — and takes the `*`/`-` bullets under it up to the next
+ * version heading. Category subheadings (`### Bug Fixes`) are dropped: a Debian
+ * change block is a flat list, and a heading rendered as a bullet reads as a change
+ * that was made.
+ *
+ * Markdown links collapse to their text (`[#1510](https://…)` → `#1510`) and bold
+ * scopes lose their asterisks, because the destination is plain text that `apt
+ * changelog` prints to a terminal.
+ *
+ * @returns one string per bullet, empty when the file does not name this version
+ */
+export function changelogEntriesFor(version, source) {
+    const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const heading = new RegExp(`^##+[ \\t]+\\[?${escaped}\\]?[^\\n]*$`, 'm');
+    const start = heading.exec(source);
+    if (start === null)
+        return [];
+    const rest = source.slice(start.index + start[0].length);
+    // The next VERSION heading, not the next heading of any depth: `### Features`
+    // is inside this release, `## [0.46.0]` is the next one.
+    const end = /^##[ \t]+\[?\d/m.exec(rest);
+    const body = end === null ? rest : rest.slice(0, end.index);
+    const entries = [];
+    for (const line of body.split('\n')) {
+        const bullet = /^[*-][ \t]+(.*\S)\s*$/.exec(line);
+        if (bullet === null)
+            continue;
+        entries.push(bullet[1]
+            .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+            .replace(/\*\*([^*]+)\*\*/g, '$1')
+            .replace(/\s+/g, ' ')
+            .trim());
+    }
+    return entries;
+}
+/**
+ * One bullet, wrapped so no line exceeds {@link WIDTH}.
+ *
+ * MEASURED, not stylistic: lintian raises `debian-changelog-line-too-long` past 80
+ * columns, and a conventional-commit subject plus its scope, its PR link and its
+ * `closes` list goes well past it. Continuation lines are indented to sit under the
+ * bullet text — Debian's change block only requires at least two leading spaces, and
+ * anything less than four would read as a new item.
+ *
+ * A single word longer than the width is left on its own line rather than broken: a
+ * URL is the usual case, and a hyphenated URL is worse than a long one.
+ */
+function wrapEntry(entry) {
+    const lines = [];
+    let line = '  *';
+    for (const word of entry.split(/\s+/)) {
+        if (word === '')
+            continue;
+        if (line.length + 1 + word.length > WIDTH && line !== '  *' && line !== '   ') {
+            lines.push(line);
+            line = '   ';
+        }
+        line += ` ${word}`;
+    }
+    lines.push(line);
+    return lines;
+}
+/** lintian's `debian-changelog-line-too-long` threshold. */
+const WIDTH = 80;
+/**
+ * The whole `changelog.Debian` file: one entry, for the version being packaged.
+ *
+ * `unstable` is the distribution and `medium` the urgency — the values `dh_make`
+ * seeds a package with, and the only honest ones for an artifact built outside any
+ * Debian suite: this package targets no release, and claiming one would put a
+ * specific false statement in a field `apt` reads.
+ *
+ * The trailer's spacing is load-bearing and is the usual way this file is got
+ * wrong: exactly one leading space, then `--`, one space, the maintainer, and TWO
+ * spaces before the date.
+ *
+ * TWO lintian tags this file still raises, both measured on lintian 2.117 against
+ * gjsify's own `.deb` and both left alone deliberately:
+ *
+ *  - `initial-upload-closes-no-bugs`, because the Debian revision is `-1` and the
+ *    entry closes no bug. It is a statement about the Debian ARCHIVE's ITP
+ *    workflow — the first upload of a new source package should close its ITP bug
+ *    — and a package built by `gjsify ship` is never uploaded there. There is no
+ *    bug number that would be true to write, so the tag is inapplicable rather
+ *    than unmet.
+ *  - `changelog-not-compressed-with-max-compression`. Policy asks for `gzip -9`
+ *    and neither `CompressionStream` nor `@gjsify/zlib` takes a level, so
+ *    `gzipDeterministic` cannot ask for one. Ledgered in `status/open-todos.md`:
+ *    the fix is a capability in the core, and stamping the header's XFL byte to
+ *    claim max compression we did not use is not one.
+ */
+export function renderDebianChangelog(settings, source, mtime) {
+    const entries = source === undefined ? [] : changelogEntriesFor(settings.version, source);
+    const fallback = settings.homepage
+        ? `Release ${settings.version}. See ${settings.homepage} for the upstream changes.`
+        : `Release ${settings.version}.`;
+    const body = (entries.length > 0 ? entries : [fallback]).flatMap(wrapEntry);
+    return [
+        `${settings.binaryName} (${settings.version}-${settings.release}) unstable; urgency=medium`,
+        '',
+        ...body,
+        '',
+        ` -- ${settings.maintainer}  ${rfc822(mtime)}`,
+        '',
+    ].join('\n');
+}

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

@@ -6,8 +6,17 @@ export interface DiscoverInput {
     ship: ConfigDataShip;
     /** `gjsify.flatpak.icon`, the pre-existing spelling of the same thing. */
     flatpakIcon?: string;
-    /** The bundle path the project declares. */
+    /** The bundle path the project declares FOR THIS TARGET. */
     declaredBundle?: string;
+    /**
+     * The entries other targets declare, which this one must not carry.
+     *
+     * See {@link withoutForeignEntries} — same class as the locale tree below,
+     * with a sharper edge: a foreign entry is not merely dead weight, it is a
+     * bundle this target's interpreter cannot load, inside an artifact that says
+     * it can.
+     */
+    foreignBundles?: readonly string[];
 }
 export declare function discoverPayload(input: DiscoverInput): DiscoveredPayload;
 /**

package/lib/utils/ship/discover.js

@@ -6,7 +6,7 @@
 // (`data/icons/hicolor/…`, `data/*.gschema.xml`) needs no configuration at all.
 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';
+import { CHANGELOG_FILE_NAMES, LICENSE_FILE_NAMES, } from './settings.js';
 const ICON_EXTENSIONS = ['.svg', '.png'];
 /**
  * The face formats every FreeType opens, with no build option deciding it.
@@ -48,13 +48,14 @@ export function discoverPayload(input) {
         // Measured on a probe package: the same `.mo` appeared at both paths. The `lib/` copy is
         // dead weight — nothing looks there — and it is the same failure that once shipped the test
         // suite: whatever is beside the bundle gets carried whether or not it belongs in a package.
-        bundleFiles: withoutLocaleTree(listFilesRecursive(bundleDir), bundleDir, projectDir, ship.localeDir),
+        bundleFiles: withoutForeignEntries(withoutLocaleTree(listFilesRecursive(bundleDir), bundleDir, projectDir, ship.localeDir), bundleDir, projectDir, input.foreignBundles ?? [], bundlePath),
         iconFiles: discoverIcons(projectDir, ship.icon ?? input.flatpakIcon),
         schemaFiles: discoverSchemas(projectDir, ship.schemas),
         typelibFiles: discoverTypelibs(projectDir, ship.bundledTypelibs),
         localeFiles,
         fontFiles: discoverFonts(projectDir, ship.fonts),
         licenseFile: discoverLicense(projectDir, ship.licenseFile),
+        changelogFile: discoverChangelog(projectDir, ship.changelogFile),
     };
 }
 /**
@@ -168,6 +169,45 @@ function discoverLocales(projectDir, dir) {
     }
     return out;
 }
+/**
+ * Drop the entries declared for OTHER targets from this target's payload.
+ *
+ * `gjsify.ship.bundle` is per OS (#1545), so a project with two hosts builds
+ * `dist/app.gjs.mjs` and `dist/app.node.mjs` into ONE directory — and staging
+ * that directory wholesale hands each artifact the other's bundle. It is not
+ * dead weight like the locale copy: on macOS it lands inside the signed `.app`,
+ * and it is a file whose only property is that this artifact's interpreter
+ * cannot load it.
+ *
+ * Only the declared entries themselves, never a guess at what else belongs to
+ * them: a bundle's shared chunks are indistinguishable from the application's
+ * own files, and dropping one would break the artifact this list exists to keep
+ * whole.
+ */
+function withoutForeignEntries(bundleFiles, bundleDir, projectDir, foreign, bundlePath) {
+    if (foreign.length === 0)
+        return bundleFiles;
+    const dropped = new Set();
+    for (const entry of foreign) {
+        const abs = isAbsolute(entry) ? entry : resolve(projectDir, entry);
+        // THIS TARGET'S OWN ENTRY, under another spelling. The foreign set is
+        // compared as declared STRINGS, and `./dist/app.mjs`, `dist/../dist/app.mjs`
+        // and an absolute path are three spellings of one file — dropping it would
+        // stage a launcher whose bundle is not in the payload, which is a worse
+        // artifact than the one this exclusion exists to prevent. Paths are the
+        // only comparison that cannot be spelled around.
+        if (abs === bundlePath)
+            continue;
+        const rel = relative(bundleDir, abs);
+        // Outside this payload — another target may build somewhere else entirely,
+        // and then there is nothing here to subtract. Same shape as the locale
+        // tree above, including the POSIX normalisation Windows needs.
+        if (rel === '' || rel.startsWith('..') || isAbsolute(rel))
+            continue;
+        dropped.add(rel.split(sep).join(posix.sep));
+    }
+    return bundleFiles.filter((file) => !dropped.has(file));
+}
 function resolveBundle(input) {
     const declared = input.declaredBundle;
     if (declared === undefined) {
@@ -336,6 +376,40 @@ function discoverLicense(projectDir, configured) {
     }
     return undefined;
 }
+/**
+ * The project's own changelog — the prose the `.deb`'s `changelog.Debian.gz` is
+ * rendered from (Debian Policy § 4.4).
+ *
+ * SAME SEARCH AS THE LICENCE, deliberately, and for the same reason: a package
+ * inside a monorepo does not carry its own copy. `packages/infra/cli` has no
+ * CHANGELOG.md and the release train writes one at the repository root, so a
+ * `projectDir`-only search would find nothing for the one in-tree project that
+ * declares `gjsify.ship`. {@link licenseSearchDirs} stops at the first ancestor
+ * that is a project root, which is what keeps an unrelated parent directory's
+ * file out.
+ *
+ * Absence is NOT an error here, unlike the licence: Policy § 4.4 requires the
+ * FILE, not a particular history, and `renderDebianChangelog` writes a
+ * one-line entry naming the version when there is no prose to quote. Refusing
+ * would make a changelog a precondition for packaging anything.
+ */
+function discoverChangelog(projectDir, configured) {
+    if (configured !== undefined) {
+        const target = resolve(projectDir, configured);
+        if (!existsSync(target)) {
+            throw new Error(`gjsify ship: the configured changelog file ${configured} does not exist.`);
+        }
+        return target;
+    }
+    for (const dir of licenseSearchDirs(projectDir)) {
+        for (const name of CHANGELOG_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 = [];