@gjsify/cli 0.47.0 → 0.49.0

package/lib/utils/base64.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Base64 for the CLI's own Node entry, which may not reach `@gjsify/buffer`.
+ *
+ * `@gjsify/buffer` exports exactly these two functions and this file duplicates
+ * them — deliberately, and the reason is a LAYER, not taste. The CLI's Node entry
+ * is the bootstrap artifact (ADR 0002): `gjsify install` links it before anything
+ * in this tree is built. `scripts/bootstrap-native-facades.mjs` emits `lib/esm`
+ * for its link-time runtime deps with plain `tsc`, and `buildCliRuntimeDeps()`
+ * resolves each one under `packages/infra/<name>`. `@gjsify/buffer` lives under
+ * `packages/node/` and its own `build` is `gjsify run build:gjsify && …`, i.e. it
+ * needs the BUNDLER — the artifact the bootstrap exists to produce. Importing it
+ * from here inverts that order, and the failure is not a type error: the ESM link
+ * fails at `bootstrap-native-facades`, so `build:infra` dies on every host before
+ * a single test runs.
+ *
+ * Measured: with `import { base64Encode } from '@gjsify/buffer'` in the CLI's Node
+ * entry, ten CI legs failed identically — "Missing at ESM link time:
+ * packages/infra/cli/node_modules/@gjsify/buffer/lib/esm/index.js, imported from
+ * lib/utils/ship/stage-manifest.js" — while all three REQUIRED checks stayed green,
+ * because `check-build-infra-order` holds the declaration order for TYPES and this
+ * is a runtime edge.
+ *
+ * So: one copy inside the CLI, imported by both call sites, rather than the two
+ * that prompted the deduplication in the first place. If the CLI ever gains a
+ * general way to reach `packages/node/*` at bootstrap time, this file is what
+ * should go.
+ */
+/**
+ * Chunked because `String.fromCharCode(...bytes)` is a spread: a tarball-sized
+ * array blows the argument limit and throws `RangeError: Maximum call stack size
+ * exceeded`. 0x8000 is the size the CLI's publish path has always used.
+ */
+export declare function base64Encode(bytes: Uint8Array): string;
+export declare function base64Decode(text: string): Uint8Array;

package/lib/utils/base64.js

@@ -0,0 +1,47 @@
+/**
+ * Base64 for the CLI's own Node entry, which may not reach `@gjsify/buffer`.
+ *
+ * `@gjsify/buffer` exports exactly these two functions and this file duplicates
+ * them — deliberately, and the reason is a LAYER, not taste. The CLI's Node entry
+ * is the bootstrap artifact (ADR 0002): `gjsify install` links it before anything
+ * in this tree is built. `scripts/bootstrap-native-facades.mjs` emits `lib/esm`
+ * for its link-time runtime deps with plain `tsc`, and `buildCliRuntimeDeps()`
+ * resolves each one under `packages/infra/<name>`. `@gjsify/buffer` lives under
+ * `packages/node/` and its own `build` is `gjsify run build:gjsify && …`, i.e. it
+ * needs the BUNDLER — the artifact the bootstrap exists to produce. Importing it
+ * from here inverts that order, and the failure is not a type error: the ESM link
+ * fails at `bootstrap-native-facades`, so `build:infra` dies on every host before
+ * a single test runs.
+ *
+ * Measured: with `import { base64Encode } from '@gjsify/buffer'` in the CLI's Node
+ * entry, ten CI legs failed identically — "Missing at ESM link time:
+ * packages/infra/cli/node_modules/@gjsify/buffer/lib/esm/index.js, imported from
+ * lib/utils/ship/stage-manifest.js" — while all three REQUIRED checks stayed green,
+ * because `check-build-infra-order` holds the declaration order for TYPES and this
+ * is a runtime edge.
+ *
+ * So: one copy inside the CLI, imported by both call sites, rather than the two
+ * that prompted the deduplication in the first place. If the CLI ever gains a
+ * general way to reach `packages/node/*` at bootstrap time, this file is what
+ * should go.
+ */
+/**
+ * Chunked because `String.fromCharCode(...bytes)` is a spread: a tarball-sized
+ * array blows the argument limit and throws `RangeError: Maximum call stack size
+ * exceeded`. 0x8000 is the size the CLI's publish path has always used.
+ */
+export function base64Encode(bytes) {
+    let str = '';
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        str += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(str);
+}
+export function base64Decode(text) {
+    const binary = atob(text);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}

package/lib/utils/cli-runtime-closure.d.ts

@@ -1,4 +1,65 @@
 import type { Workspace } from '@gjsify/workspace';
+/**
+ * Literal module specifiers of `code`: static `import`/`export … from`, plus
+ * `import('<literal>')`.
+ *
+ * acorn rather than a regex — see the header. `allowHashBang` because the CLI's
+ * own entry is a bin (`#!/usr/bin/env node`), and a parse failure yields NO
+ * specifiers, which under-selects rather than mis-selects.
+ */
+export interface SpecifierNode {
+    type?: string;
+    value?: unknown;
+    expressions?: unknown[];
+    quasis?: Array<{
+        value?: {
+            cooked?: unknown;
+        };
+    }>;
+}
+/**
+ * The string a node names statically, or `null` when it is computed.
+ *
+ * A substitution-free TEMPLATE LITERAL is as static as a quoted string, and
+ * skipping it is not hypothetical: the minifier rewrites `await
+ * import('gi://GLib?version=2.0')` to a backtick form, so a Literal-only reader
+ * silently loses every dynamic import in a built bundle.
+ *
+ * Not named for specifiers, because it does not only read them: the same
+ * question is asked of a CALL ARGUMENT by `utils/ship/gi-namespaces.ts`, whose
+ * `requireGi("Gtk", "4.0")` carries a namespace and a version in exactly the two
+ * spellings above.
+ */
+export declare function staticStringValue(node: SpecifierNode | undefined): string | null;
+/** One node of the walk: whatever acorn produced, seen as a bag of properties. */
+export type AstNode = {
+    type?: string;
+} & Record<string, unknown>;
+/**
+ * Parse `code` as a module and call `visit` for every node in it.
+ *
+ * Exported because a SECOND parse is how the two readers of a built bundle
+ * would drift apart: {@link moduleSpecifiers} answers "what does this file
+ * import" and `utils/ship/gi-namespaces.ts` answers "which GI namespaces does
+ * it load", and the second question has an answer the first cannot see — a
+ * `--app node` bundle carries no `gi://` specifier at all, only the
+ * `requireGi()` calls the bundler rewrote them into. One walker, two readers.
+ *
+ * A parse failure yields NO nodes rather than throwing: every caller is
+ * summarising a file it did not write, and under-selecting is the failure mode
+ * that keeps a correct project buildable.
+ */
+export declare function walkModuleAst(code: string, visit: (node: AstNode) => void): void;
+/**
+ * The module `node` imports from, or `null` when `node` is not an import at all.
+ *
+ * FOUR node types, in one place. Every reader of a built bundle in this tree asks
+ * the same question of the same four — a static `import`, both `export … from`
+ * forms and `import()` — and each copy of that list is a chance for one reader to
+ * miss a form the others catch. The bare side-effect `import "gi://Soup"` is what
+ * that costs when it happens (`utils/ship/gi-namespaces.ts`).
+ */
+export declare function importedSpecifier(node: AstNode): string | null;
 export declare function moduleSpecifiers(code: string): string[];
 export interface CliRuntimeClosureOptions {
     /**

package/lib/utils/cli-runtime-closure.js

@@ -79,14 +79,19 @@ function splitWorkspaceSpecifier(specifier, byName) {
     return null;
 }
 /**
- * The string a module specifier node names, or `null` when it is computed.
+ * The string a node names statically, or `null` when it is computed.
  *
  * A substitution-free TEMPLATE LITERAL is as static as a quoted string, and
  * skipping it is not hypothetical: the minifier rewrites `await
  * import('gi://GLib?version=2.0')` to a backtick form, so a Literal-only reader
  * silently loses every dynamic import in a built bundle.
+ *
+ * Not named for specifiers, because it does not only read them: the same
+ * question is asked of a CALL ARGUMENT by `utils/ship/gi-namespaces.ts`, whose
+ * `requireGi("Gtk", "4.0")` carries a namespace and a version in exactly the two
+ * spellings above.
  */
-function literalSpecifier(node) {
+export function staticStringValue(node) {
     if (node?.type === 'Literal')
         return typeof node.value === 'string' ? node.value : null;
     if (node?.type === 'TemplateLiteral' && node.expressions?.length === 0) {
@@ -95,39 +100,71 @@ function literalSpecifier(node) {
     }
     return null;
 }
-export function moduleSpecifiers(code) {
+/**
+ * Parse `code` as a module and call `visit` for every node in it.
+ *
+ * Exported because a SECOND parse is how the two readers of a built bundle
+ * would drift apart: {@link moduleSpecifiers} answers "what does this file
+ * import" and `utils/ship/gi-namespaces.ts` answers "which GI namespaces does
+ * it load", and the second question has an answer the first cannot see — a
+ * `--app node` bundle carries no `gi://` specifier at all, only the
+ * `requireGi()` calls the bundler rewrote them into. One walker, two readers.
+ *
+ * A parse failure yields NO nodes rather than throwing: every caller is
+ * summarising a file it did not write, and under-selecting is the failure mode
+ * that keeps a correct project buildable.
+ */
+export function walkModuleAst(code, visit) {
     let ast;
     try {
         ast = acorn.parse(code, { ecmaVersion: 'latest', sourceType: 'module', allowHashBang: true });
     }
     catch {
-        return [];
+        return;
     }
-    const out = [];
-    const visit = (node) => {
+    const descend = (node) => {
         if (!node || typeof node !== 'object')
             return;
         if (Array.isArray(node)) {
             for (const child of node)
-                visit(child);
+                descend(child);
             return;
         }
         const n = node;
-        if (n.type === 'ImportDeclaration' ||
-            n.type === 'ExportNamedDeclaration' ||
-            n.type === 'ExportAllDeclaration' ||
-            n.type === 'ImportExpression') {
-            const specifier = literalSpecifier(n.source);
-            if (specifier !== null)
-                out.push(specifier);
-        }
+        visit(n);
         for (const [key, value] of Object.entries(n)) {
             if (key === 'type' || key === 'start' || key === 'end' || key === 'loc')
                 continue;
-            visit(value);
+            descend(value);
         }
     };
-    visit(ast);
+    descend(ast);
+}
+/**
+ * The module `node` imports from, or `null` when `node` is not an import at all.
+ *
+ * FOUR node types, in one place. Every reader of a built bundle in this tree asks
+ * the same question of the same four — a static `import`, both `export … from`
+ * forms and `import()` — and each copy of that list is a chance for one reader to
+ * miss a form the others catch. The bare side-effect `import "gi://Soup"` is what
+ * that costs when it happens (`utils/ship/gi-namespaces.ts`).
+ */
+export function importedSpecifier(node) {
+    if (node.type !== 'ImportDeclaration' &&
+        node.type !== 'ExportNamedDeclaration' &&
+        node.type !== 'ExportAllDeclaration' &&
+        node.type !== 'ImportExpression') {
+        return null;
+    }
+    return staticStringValue(node.source);
+}
+export function moduleSpecifiers(code) {
+    const out = [];
+    walkModuleAst(code, (node) => {
+        const specifier = importedSpecifier(node);
+        if (specifier !== null)
+            out.push(specifier);
+    });
     return out;
 }
 /** The file a relative specifier names, probing the extensionless spellings Node accepts. */

package/lib/utils/detect-native-packages.d.ts

@@ -233,6 +233,37 @@ export declare function resolveHostLibc(input: {
  * reach it.
  */
 export declare function detectHostLibc(platform: string): HostLibc | null;
+/**
+ * The packages a musl host had to take the DEFAULT prebuild of, because they ship
+ * no `-musl` directory — the fallback {@link hostPlatformTokens} deliberately
+ * allows, named so a caller can report it. Returns names and prints nothing: this
+ * module resolves, and `libc` is a parameter for the same reason it is on every
+ * other function here (there is no musl runner in this repo's CI, so an injected
+ * `libc: 'musl'` is the only way the branch executes).
+ *
+ * Why a fallback that mostly WORKS is worth naming. musl's loader resolves
+ * `libc.so.6`/`libm.so.6` to itself, so a glibc-linked prebuild loads — and a
+ * bridge that records no libc at all then runs correctly, which is why the
+ * fallback exists rather than resolving to null. The one that is NOT agnostic dies
+ * at `dlopen` on its first glibc-only symbol, far from its cause. Measured on a
+ * OnePlus 6 (postmarketOS v26.06, musl 1.2.6, aarch64, gjs 1.88.1) against the
+ * published 0.48.0 train: nine of ten prebuilds loaded, while
+ * `@gjsify/lightningcss-native-linux-arm64` answered `gnu_get_libc_version: symbol
+ * not found`. `gjsify install` had printed "System dependencies OK", and the first
+ * symptom was rolldown reporting `Could not load src/application.css` — the CSS
+ * bridge silently absent from the bundle. Nothing in that chain names libc, which
+ * is what makes the report worth more than the failure.
+ *
+ * Membership goes through {@link parsePlatformToken}, not the suffix constant, so
+ * this does not become a second reader of the libc half of the token grammar —
+ * `darwin-arm64-musl` is a malformed token rather than a musl build, and only the
+ * grammar knows that.
+ *
+ * TODO(open-todos: `-musl` prebuild package is published): naming the fallback is
+ * not fixing it. No `-musl` target is published for any bridge, so on a musl host
+ * this reports every prebuild in the tree and there is nothing to fall back FROM.
+ */
+export declare function muslPrebuildFallbacks(libc: HostLibc | null, packages: readonly NativePackage[]): string[];
 /**
  * The environment-variable name the host's dynamic loader consults for an
  * additional shared-library search path, plus the separator its search paths

package/lib/utils/detect-native-packages.js

@@ -22,7 +22,7 @@
 // win32 AND musl branches unit-testable from a glibc Linux host. The host values
 // are read only at the outermost call site, as a default.
 import { readdirSync, existsSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 import { readPackageJson } from './pkg-json.js';
 import { composeDyldFallback, systemGiLibraryDirs } from './system-gi.js';
 /**
@@ -500,6 +500,42 @@ export function detectHostLibc(platform) {
     const muslLoaderPresent = existsSync('/lib') && readdirSync('/lib').some((f) => f.startsWith('ld-musl-'));
     return resolveHostLibc({ platform, glibcVersionRuntime, muslLoaderPresent });
 }
+/**
+ * The packages a musl host had to take the DEFAULT prebuild of, because they ship
+ * no `-musl` directory — the fallback {@link hostPlatformTokens} deliberately
+ * allows, named so a caller can report it. Returns names and prints nothing: this
+ * module resolves, and `libc` is a parameter for the same reason it is on every
+ * other function here (there is no musl runner in this repo's CI, so an injected
+ * `libc: 'musl'` is the only way the branch executes).
+ *
+ * Why a fallback that mostly WORKS is worth naming. musl's loader resolves
+ * `libc.so.6`/`libm.so.6` to itself, so a glibc-linked prebuild loads — and a
+ * bridge that records no libc at all then runs correctly, which is why the
+ * fallback exists rather than resolving to null. The one that is NOT agnostic dies
+ * at `dlopen` on its first glibc-only symbol, far from its cause. Measured on a
+ * OnePlus 6 (postmarketOS v26.06, musl 1.2.6, aarch64, gjs 1.88.1) against the
+ * published 0.48.0 train: nine of ten prebuilds loaded, while
+ * `@gjsify/lightningcss-native-linux-arm64` answered `gnu_get_libc_version: symbol
+ * not found`. `gjsify install` had printed "System dependencies OK", and the first
+ * symptom was rolldown reporting `Could not load src/application.css` — the CSS
+ * bridge silently absent from the bundle. Nothing in that chain names libc, which
+ * is what makes the report worth more than the failure.
+ *
+ * Membership goes through {@link parsePlatformToken}, not the suffix constant, so
+ * this does not become a second reader of the libc half of the token grammar —
+ * `darwin-arm64-musl` is a malformed token rather than a musl build, and only the
+ * grammar knows that.
+ *
+ * TODO(open-todos: `-musl` prebuild package is published): naming the fallback is
+ * not fixing it. No `-musl` target is published for any bridge, so on a musl host
+ * this reports every prebuild in the tree and there is nothing to fall back FROM.
+ */
+export function muslPrebuildFallbacks(libc, packages) {
+    if (libc !== 'musl')
+        return [];
+    const fellBack = packages.filter((pkg) => parsePlatformToken(basename(pkg.prebuildsDir)).libc !== 'musl');
+    return fellBack.map((pkg) => pkg.name);
+}
 /**
  * The environment-variable name the host's dynamic loader consults for an
  * additional shared-library search path, plus the separator its search paths

package/lib/utils/double-dash-args.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Everything after the `--` separator, as an argv.
+ *
+ * @param args a yargs-parsed argument object from a command whose builder sets
+ *   `parserConfiguration({ 'populate--': true, 'parse-positional-numbers': false })`
+ * @throws if an entry is not a string, i.e. if that configuration is missing
+ */
+export declare function doubleDashArgs(args: object): string[];

package/lib/utils/double-dash-args.js

@@ -0,0 +1,64 @@
+// The argv a caller wrote after `--`, read back off yargs.
+//
+// THE INCIDENT (#1531). `foreach.ts` and `run.ts` each read `args['--']` and
+// narrowed it with `.filter((v): v is string => typeof v === 'string')`. That
+// reads like a type narrowing and is a DELETION: yargs types a bare number in
+// its `populate--` array as a `number`, so the value disappears and the option
+// in front of it swallows the next flag. Measured against this repo's own
+// yargs 18.0.0:
+//
+//   in    : gjsify publish --verify-timeout 5 --tag latest
+//   raw   : ["gjsify","publish","--verify-timeout",5,"--tag","latest"]
+//   filter: ["gjsify","publish","--verify-timeout","--tag","latest"]
+//
+// That argv shipped: `npm:publish` passes `--verify-timeout 5 --tag latest`,
+// and release run 33804937881 echoed `--verify-timeout --tag latest` 209 times
+// — `--verify-timeout` taking `--tag` as its value, `latest` a stray
+// positional, `--tag latest` gone. Nobody noticed because npm's default
+// dist-tag IS `latest`, which is luck rather than design.
+//
+// TWO HALVES, AND THE FIRST ONE IS THE FIX. A coercion here (`String(v)`) would
+// recover the value and still lose its SPELLING — measured against yargs 18.0.0,
+// `1.0` comes back as 1, `0.10` as 0.1, `0x10` as 16 and `1e3` as 1000, and an
+// argv is text, not arithmetic. (A leading zero is NOT in that set: `007` stays
+// the string yargs was given. It reads like the obvious example and is the one
+// shape here that never broke.) So the parse is corrected at
+// the source: every command that sets `populate--` also sets
+// `parse-positional-numbers: false`, which leaves `_`, the variadic positionals
+// and the `--` tail as the strings the user typed while option values declared
+// `type: 'number'` are still parsed (measured: `--jobs 4` stays `4` the number).
+//
+// This function is the second half. It does NOT coerce — with the parser
+// configured as above a non-string cannot arrive, so one that does means the
+// configuration was dropped, and that is the failure to name rather than to
+// paper over. A silent `.filter()` over a parser-produced array is the wrong
+// tool wherever the array is data rather than a union.
+//
+// ONE reader for all of it, because there were three and they disagreed:
+// `foreach.ts` (twice) and `run.ts` filtered, `dlx.ts` coerced. The drifted
+// copies are the ones that shipped the wrong argv.
+/**
+ * Everything after the `--` separator, as an argv.
+ *
+ * @param args a yargs-parsed argument object from a command whose builder sets
+ *   `parserConfiguration({ 'populate--': true, 'parse-positional-numbers': false })`
+ * @throws if an entry is not a string, i.e. if that configuration is missing
+ */
+export function doubleDashArgs(args) {
+    const raw = args['--'];
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new Error(`gjsify: internal error — yargs' \`--\` slot holds a ${typeof raw} rather than an array, so the ` +
+            'arguments after `--` cannot be forwarded. The command builder must set ' +
+            "`parserConfiguration({ 'populate--': true })`.");
+    }
+    return raw.map((value, index) => {
+        if (typeof value === 'string')
+            return value;
+        throw new Error(`gjsify: internal error — the argument after \`--\` at position ${index} arrived as a ` +
+            `${typeof value} (${String(value)}) instead of a string, so forwarding it would change what ` +
+            'the caller wrote. The command builder must set ' +
+            "`parserConfiguration({ 'parse-positional-numbers': false })` alongside `populate--`.");
+    });
+}

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');
+}