@gjsify/cli 0.39.0 → 0.40.0

package/lib/utils/publish-headers.js

@@ -98,19 +98,45 @@ export function cliVersion() {
 }
 /** Nearest ancestor `package.json` whose `name` is `@gjsify/cli`; '' when none. */
 function walkForCliVersion() {
+    const dir = cliPackageDir();
+    if (!dir)
+        return '';
+    try {
+        const pkg = JSON.parse(readFileSync(`${dir}/package.json`, 'utf8'));
+        if (typeof pkg.version === 'string')
+            return pkg.version;
+    }
+    catch {
+        /* cliPackageDir() already parsed it once; a race or a permission flip lands here */
+    }
+    return '';
+}
+/**
+ * Directory of the RUNNING `@gjsify/cli` package — the nearest ancestor of this
+ * module holding a `package.json` named `@gjsify/cli`; `null` when none.
+ *
+ * The climb, not a fixed `'..'` hop, for the reason {@link cliVersion} states: the
+ * package is dual-entry and the two entries sit at different depths.
+ * `GJSIFY_CLI_PACKAGE_JSON` overrides the starting point, same as for the version.
+ *
+ * Exported because the answer to "where am I installed" is the same question as
+ * "which version am I", and this file is where that climb lives — a second copy
+ * elsewhere is the drift `check-cli-own-version-read.mjs` exists to prevent.
+ */
+export function cliPackageDir() {
     const override = globalThis.process?.env?.['GJSIFY_CLI_PACKAGE_JSON'];
     let dir;
     try {
         dir = override ? dirname(override) : dirname(fileURLToPath(import.meta.url));
     }
     catch {
-        return '';
+        return null;
     }
     for (let i = 0; i < 12; i++) {
         try {
             const pkg = JSON.parse(readFileSync(`${dir}/package.json`, 'utf8'));
-            if (pkg.name === '@gjsify/cli' && typeof pkg.version === 'string')
-                return pkg.version;
+            if (pkg.name === '@gjsify/cli')
+                return dir;
         }
         catch {
             /* no manifest here (or unreadable) — keep climbing */
@@ -120,7 +146,7 @@ function walkForCliVersion() {
             break;
         dir = parent;
     }
-    return '';
+    return null;
 }
 /**
  * npm-CLI-shaped user-agent, mirroring npm-registry-fetch's

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

@@ -0,0 +1,21 @@
+export interface ArMember {
+    /** Member name, at most 16 bytes. */
+    name: string;
+    /** Member contents. */
+    data: Uint8Array;
+    /** Unix mtime in seconds. Default 0 — deterministic archives. */
+    mtime?: number;
+    /** POSIX mode. Default 0o100644. */
+    mode?: number;
+}
+/**
+ * Build an ar archive.
+ *
+ * Names are written space-padded with NO trailing `/`: that is what
+ * `dpkg-deb -b` emits and what dpkg's own reader expects for a `.deb`. The
+ * GNU `<name>/` convention and the BSD `#1/<len>` long-name extension are both
+ * for archives with names longer than 15 bytes — a `.deb`'s three members are
+ * `debian-binary`, `control.tar.<ext>` and `data.tar.<ext>`, all short, so
+ * neither extension can arise and refusing a long name is honest.
+ */
+export declare function createArArchive(members: readonly ArMember[]): Uint8Array;

package/lib/utils/ship/ar.js

@@ -0,0 +1,57 @@
+// The `ar` container a `.deb` is.
+//
+// Two hundred lines of dependency avoided: a Debian package is an ar archive of
+// exactly three members, and the format is a text header per member with no
+// index, no compression and no symbol table. Writing it here keeps `gjsify
+// ship` free of `dpkg-deb` — which matters beyond convenience, because this
+// project's CI runs on Fedora and `dpkg-deb` is not installable there without
+// dragging in a foreign package manager. The same reasoning produced
+// `gjsify flatpak sources` (a Node-free reader replacing
+// `flatpak-node-generator`), and it has the same payoff: the packer runs
+// wherever the CLI runs, including under GJS.
+import { concatBytes, encodeUtf8 } from './bytes.js';
+const GLOBAL_HEADER = '!<arch>\n';
+const HEADER_SIZE = 60;
+/**
+ * Build an ar archive.
+ *
+ * Names are written space-padded with NO trailing `/`: that is what
+ * `dpkg-deb -b` emits and what dpkg's own reader expects for a `.deb`. The
+ * GNU `<name>/` convention and the BSD `#1/<len>` long-name extension are both
+ * for archives with names longer than 15 bytes — a `.deb`'s three members are
+ * `debian-binary`, `control.tar.<ext>` and `data.tar.<ext>`, all short, so
+ * neither extension can arise and refusing a long name is honest.
+ */
+export function createArArchive(members) {
+    const chunks = [encodeUtf8(GLOBAL_HEADER)];
+    for (const member of members) {
+        chunks.push(buildMemberHeader(member));
+        chunks.push(member.data);
+        // Members are aligned to an even offset; the pad byte is `\n`.
+        if (member.data.byteLength % 2 === 1)
+            chunks.push(encodeUtf8('\n'));
+    }
+    return concatBytes(chunks);
+}
+function buildMemberHeader(member) {
+    // `pad()` below is what refuses an over-long name, with the width in the
+    // message — a second length check here would differ only for a non-ASCII
+    // name, and all three member names are literals.
+    const header = pad(member.name, 16) +
+        pad(String(member.mtime ?? 0), 12) +
+        pad('0', 6) + // uid
+        pad('0', 6) + // gid
+        pad((member.mode ?? 0o100644).toString(8), 8) +
+        pad(String(member.data.byteLength), 10) +
+        '`\n';
+    if (header.length !== HEADER_SIZE) {
+        throw new Error(`gjsify ship: internal error — ar header is ${header.length} bytes, expected ${HEADER_SIZE}.`);
+    }
+    return encodeUtf8(header);
+}
+function pad(value, width) {
+    if (value.length > width) {
+        throw new Error(`gjsify ship: ar header field "${value}" does not fit in ${width} bytes.`);
+    }
+    return value.padEnd(width, ' ');
+}

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

@@ -0,0 +1,4 @@
+/** Join byte chunks into one buffer. */
+export declare function concatBytes(chunks: readonly Uint8Array[]): Uint8Array;
+/** UTF-8 encode. The archive formats are byte formats; every length is a BYTE length. */
+export declare function encodeUtf8(value: string): Uint8Array;

package/lib/utils/ship/bytes.js

@@ -0,0 +1,23 @@
+// The byte-level helpers all three writers need.
+//
+// `concatBytes` existed once per writer before this file did — the same nine
+// lines in `ar.ts`, `cpio.ts` and `rpm.ts`. The second copy is where a helper
+// belongs (root AGENTS.md § Code anti-patterns): a drifted copy of THIS
+// function would not throw, it would silently produce a truncated archive.
+/** Join byte chunks into one buffer. */
+export function concatBytes(chunks) {
+    let total = 0;
+    for (const chunk of chunks)
+        total += chunk.byteLength;
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+/** UTF-8 encode. The archive formats are byte formats; every length is a BYTE length. */
+export function encodeUtf8(value) {
+    return new TextEncoder().encode(value);
+}

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

@@ -0,0 +1,22 @@
+export interface CpioEntry {
+    /** Archive path. RPM spells these `./usr/bin/foo`. */
+    name: string;
+    /** Full st_mode, i.e. file type bits OR permission bits. */
+    mode: number;
+    /** File contents; empty for directories and symlinks. */
+    data?: Uint8Array;
+    /** Symlink target — stored as the entry's data, per the cpio format. */
+    linkTarget?: string;
+    /** Unix mtime in seconds. Default 0. */
+    mtime?: number;
+    /** Inode number. RPM numbers entries from 1. */
+    ino?: number;
+    /** Hardlink count. Default 1. */
+    nlink?: number;
+}
+/** POSIX `st_mode` file-type bits, spelled out so call sites read as intent. */
+export declare const S_IFREG = 32768;
+export declare const S_IFDIR = 16384;
+export declare const S_IFLNK = 40960;
+/** Build a cpio archive, terminated by the mandatory `TRAILER!!!` entry. */
+export declare function createCpioArchive(entries: readonly CpioEntry[]): Uint8Array;

package/lib/utils/ship/cpio.js

@@ -0,0 +1,93 @@
+// The "new ASCII" cpio archive (magic `070701`) an RPM carries as its payload.
+//
+// Every field is 8 hex digits, which makes the format trivially writable and —
+// more usefully — trivially INSPECTABLE: `rpm2cpio x.rpm | cpio -it` reads what
+// this writes, so the e2e suite has an oracle that shares no code with the
+// writer. (rpm itself formats them with `%8.8lx`, i.e. LOWERCASE; both parse,
+// and this writer emits uppercase.)
+//
+// Two padding rules, both easy to get subtly wrong and both silent when wrong:
+// the filename (including its NUL) is padded so that the DATA starts on a
+// 4-byte boundary counted from the start of the header, and the data itself is
+// padded so the NEXT header does too.
+import { concatBytes, encodeUtf8 } from './bytes.js';
+const MAGIC = '070701';
+const HEADER_FIELDS = 13;
+const HEADER_SIZE = MAGIC.length + HEADER_FIELDS * 8; // 110
+/** POSIX `st_mode` file-type bits, spelled out so call sites read as intent. */
+export const S_IFREG = 0o100000;
+export const S_IFDIR = 0o040000;
+export const S_IFLNK = 0o120000;
+/** Build a cpio archive, terminated by the mandatory `TRAILER!!!` entry. */
+export function createCpioArchive(entries) {
+    const chunks = [];
+    let offset = 0;
+    entries.forEach((entry, index) => {
+        const body = entry.linkTarget !== undefined ? encodeUtf8(entry.linkTarget) : (entry.data ?? new Uint8Array(0));
+        const nameBytes = encodeUtf8(`${entry.name}\0`);
+        const header = buildHeader({
+            ino: entry.ino ?? index + 1,
+            mode: entry.mode,
+            nlink: entry.nlink ?? 1,
+            mtime: entry.mtime ?? 0,
+            filesize: body.byteLength,
+            namesize: nameBytes.byteLength,
+        });
+        offset = push(chunks, header, offset);
+        offset = push(chunks, nameBytes, offset);
+        offset = padTo4(chunks, offset);
+        offset = push(chunks, body, offset);
+        offset = padTo4(chunks, offset);
+    });
+    // The archive ends at the entry NAMED `TRAILER!!!` — that name is the
+    // signal, not any of the numeric fields. rpm writes `nlink = 1` there and
+    // zeroes the rest, so this does too.
+    const trailerName = encodeUtf8('TRAILER!!!\0');
+    offset = push(chunks, buildHeader({ ino: 0, mode: 0, nlink: 1, mtime: 0, filesize: 0, namesize: trailerName.byteLength }), offset);
+    offset = push(chunks, trailerName, offset);
+    padTo4(chunks, offset);
+    return concatBytes(chunks);
+}
+function buildHeader(fields) {
+    const header = MAGIC +
+        hex8(fields.ino) +
+        hex8(fields.mode) +
+        hex8(0) + // uid — packages install as root
+        hex8(0) + // gid
+        hex8(fields.nlink) +
+        hex8(fields.mtime) +
+        hex8(fields.filesize) +
+        hex8(0) + // devmajor
+        hex8(0) + // devminor
+        hex8(0) + // rdevmajor
+        hex8(0) + // rdevminor
+        hex8(fields.namesize) +
+        hex8(0); // check — unused for 070701, but the field is not optional
+    if (header.length !== HEADER_SIZE) {
+        throw new Error(`gjsify ship: internal error — cpio header is ${header.length} bytes, expected ${HEADER_SIZE}.`);
+    }
+    return encodeUtf8(header);
+}
+function hex8(value) {
+    if (value < 0 || !Number.isInteger(value)) {
+        throw new Error(`gjsify ship: cpio header field must be a non-negative integer, got ${value}.`);
+    }
+    const text = value.toString(16).toUpperCase();
+    if (text.length > 8) {
+        throw new Error(`gjsify ship: cpio header field ${value} does not fit in 8 hex digits.`);
+    }
+    return text.padStart(8, '0');
+}
+function push(chunks, bytes, offset) {
+    if (bytes.byteLength > 0)
+        chunks.push(bytes);
+    return offset + bytes.byteLength;
+}
+function padTo4(chunks, offset) {
+    const remainder = offset % 4;
+    if (remainder === 0)
+        return offset;
+    const padding = 4 - remainder;
+    chunks.push(new Uint8Array(padding));
+    return offset + padding;
+}

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

@@ -0,0 +1,24 @@
+import type { PayloadEntry } from './payload.js';
+import type { ShipSettings } from './types.js';
+export interface DebInputs {
+    settings: ShipSettings;
+    /** The staged payload, prefix-relative. */
+    payload: readonly PayloadEntry[];
+    /** Install prefix, e.g. `/usr`. */
+    prefix: string;
+    /** Already-derived dependency list, in `name`/`name >= version` form. */
+    depends: readonly string[];
+    /** Debian architecture (`amd64`, `all`, …). */
+    archLabel: string;
+    /** Unix seconds stamped into every header. */
+    mtime: number;
+}
+export declare function buildDeb(inputs: DebInputs): Promise<Uint8Array>;
+/**
+ * `./`, `./usr/`, `./usr/bin/`, … for every path in the archive.
+ *
+ * dpkg opens each file with `O_CREAT | O_EXCL` and never creates a parent, so
+ * a missing directory entry is `cannot create '<path>'` mid-unpack — with the
+ * package half-installed.
+ */
+export declare function ancestorDirectories(paths: readonly string[]): string[];

package/lib/utils/ship/deb.js

@@ -0,0 +1,118 @@
+// The `.deb` packer.
+//
+// A Debian package is `debian-binary` + `control.tar.gz` + `data.tar.gz` in an
+// ar container, and every one of those three parts already had a writer in
+// this tree (`utils/ship/ar.ts`, `@gjsify/tar`) or is four bytes long. So no
+// `dpkg-deb`, no vendored Go binary, no download at ship time — which is what
+// lets the packer run under GJS, offline, on a Fedora CI image where dpkg does
+// not exist.
+//
+// Everything below that looks like a detail is a documented dpkg failure mode:
+// the ancestor-directory expansion (dpkg never calls `mkdir -p` and an ENOENT
+// aborts the unpack), the `md5sums` path spelling (no `./`, exactly two
+// spaces), the final newline in `control` (its absence is a parse error), and
+// the gzip header's mtime (not a dpkg failure at all — it silently destroys
+// reproducibility instead).
+import { createHash } from 'node:crypto';
+import { posix } from 'node:path';
+import { createTarball } from '@gjsify/tar';
+import { createArArchive } from './ar.js';
+import { formatDebDepend } from './depends.js';
+import { gzipDeterministic } from './gzip.js';
+import { renderDebScripts } from './scripts.js';
+export async function buildDeb(inputs) {
+    const { settings, payload, mtime } = inputs;
+    const prefix = inputs.prefix.replace(/^\/+/, '');
+    const named = payload.map((entry) => ({ ...entry, tarPath: `./${posix.join(prefix, entry.path)}` }));
+    const directories = ancestorDirectories(named.map((entry) => entry.tarPath));
+    const dataEntries = [
+        ...directories.map((name) => ({ name, mode: 0o755, mtime, directory: true })),
+        ...named.map((entry) => ({ name: entry.tarPath, body: entry.data, mode: entry.mode, mtime })),
+    ];
+    const dataTar = await gzipDeterministic(createTarball(dataEntries));
+    // Policy 5.6.20: regular files and symlinks round UP to whole KiB, every
+    // other filesystem object counts as one. Getting the unit wrong (bytes
+    // instead of KiB) is invisible — dpkg never validates this field, apt just
+    // shows the user a wrong number.
+    const installedSize = named.reduce((total, entry) => total + Math.ceil(entry.data.byteLength / 1024), 0) + directories.length;
+    const control = renderControl(inputs, installedSize);
+    const md5sums = named
+        .map((entry) => `${createHash('md5').update(entry.data).digest('hex')}  ${entry.tarPath.slice(2)}\n`)
+        .join('');
+    const controlEntries = [
+        { name: './', mode: 0o755, mtime, directory: true },
+        { name: './control', body: control, mode: 0o644, mtime },
+        { name: './md5sums', body: md5sums, mode: 0o644, mtime },
+    ];
+    const maintainerScripts = renderDebScripts(settings, inputs.prefix);
+    for (const [name, body] of Object.entries(maintainerScripts)) {
+        // dpkg refuses a maintainer script outside 0555–0775 with the mode in
+        // the error, so this is 0755 rather than "whatever the source had".
+        controlEntries.push({ name: `./${name}`, body, mode: 0o755, mtime });
+    }
+    const controlTar = await gzipDeterministic(createTarball(controlEntries));
+    return createArArchive([
+        { name: 'debian-binary', data: new TextEncoder().encode('2.0\n'), mtime },
+        { name: 'control.tar.gz', data: controlTar, mtime },
+        { name: 'data.tar.gz', data: dataTar, mtime },
+    ]);
+}
+/**
+ * Collapse a value that has to occupy exactly one control line.
+ *
+ * A newline here does not corrupt the file — it FORGES a field: a summary
+ * pasted with a hard wrap turns its second line into whatever that line happens
+ * to start with, and `Pre-Depends: …` is a real thing to end up with by
+ * accident. The extended description already collapses whitespace per
+ * paragraph; these fields did not.
+ */
+function singleLine(value) {
+    return value.replace(/[\r\n]+/g, ' ').trim();
+}
+/**
+ * `./`, `./usr/`, `./usr/bin/`, … for every path in the archive.
+ *
+ * dpkg opens each file with `O_CREAT | O_EXCL` and never creates a parent, so
+ * a missing directory entry is `cannot create '<path>'` mid-unpack — with the
+ * package half-installed.
+ */
+export function ancestorDirectories(paths) {
+    const directories = new Set(['./']);
+    for (const path of paths) {
+        const parts = path.replace(/^\.\//, '').split('/');
+        parts.pop();
+        let current = '.';
+        for (const part of parts) {
+            current = `${current}/${part}`;
+            directories.add(`${current}/`);
+        }
+    }
+    return [...directories].sort();
+}
+function renderControl(inputs, installedSize) {
+    const { settings } = inputs;
+    const fields = [
+        ['Package', settings.binaryName],
+        ['Version', `${settings.version}-${settings.release}`],
+        ['Architecture', inputs.archLabel],
+        ['Maintainer', settings.maintainer],
+        ['Installed-Size', String(installedSize)],
+    ];
+    if (inputs.depends.length > 0)
+        fields.push(['Depends', inputs.depends.map(formatDebDepend).join(', ')]);
+    fields.push(['Section', settings.section], ['Priority', 'optional']);
+    if (settings.homepage)
+        fields.push(['Homepage', settings.homepage]);
+    const lines = fields.map(([key, value]) => `${key}: ${singleLine(value)}`);
+    // The extended description is continuation lines: one leading space per
+    // line, and a lone ` .` for a paragraph break — a truly blank line ends
+    // the field and silently truncates everything after it.
+    lines.push(`Description: ${singleLine(settings.summary)}`);
+    const body = settings.description.filter((paragraph) => paragraph !== settings.summary);
+    body.forEach((paragraph, index) => {
+        if (index > 0)
+            lines.push(' .');
+        lines.push(` ${paragraph}`);
+    });
+    return `${lines.join('\n')}\n`;
+}

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

@@ -0,0 +1,62 @@
+import type { FormatId } from './types.js';
+/**
+ * The GJS the bundles target (root AGENTS.md § Constraints: GJS 1.86 /
+ * SpiderMonkey 140, Rolldown `firefox140`). A `--app gjs` bundle can carry
+ * ES2024 syntax an older SpiderMonkey does not parse, so this is a real floor
+ * and not a formality.
+ *
+ * It is also, today, UNSATISFIABLE ON DEBIAN — measured, not assumed: Debian
+ * went 1.82.3 (trixie) straight to 1.88.1 (forky), skipping 1.84 and 1.86, so
+ * no Debian suite ships a `gjs` that satisfies `>= 1.86`. Emitting the honest
+ * floor means a `.deb` apt REFUSES on trixie; lowering it silently would mean
+ * one apt installs and the app then dies on a syntax error. `warnAboutGjsFloor`
+ * exists so the choice is visible at ship time, and `gjsify.ship.minGjsVersion`
+ * is how a project whose bundle really does run on older GJS lowers it.
+ */
+export declare const DEFAULT_GJS_FLOOR = "1.86";
+/**
+ * Warn when the derived floor cannot be satisfied by a released Debian.
+ * Returns the warning lines; empty when the floor is fine.
+ */
+export declare function warnAboutGjsFloor(format: FormatId, floor: string): string[];
+export interface DependsInputs {
+    /** GI namespaces the bundle imports, in `Ns-Version` spelling. */
+    namespaces: readonly string[];
+    /** `'app'` installs a desktop entry and icons; `'cli'` does not. */
+    kind: 'app' | 'cli';
+    /** Whether the payload installs GSettings schemas. */
+    hasSchemas: boolean;
+    /** User-supplied additions for this format. */
+    extra: readonly string[];
+    /** Project-supplied table rows, filling gaps in {@link TYPELIB_PACKAGES}. */
+    typelibPackages?: Record<string, {
+        deb: string;
+        rpm: string;
+    }>;
+    /** Minimum GJS. Default {@link DEFAULT_GJS_FLOOR}. */
+    minGjsVersion?: string;
+}
+/**
+ * The `Depends:` / `Requires:` list for one format.
+ *
+ * @throws when a namespace has no entry in the table — see the module header.
+ */
+export declare function deriveDepends(format: FormatId, inputs: DependsInputs): string[];
+/** One parsed dependency. `relation`/`version` are absent for an unversioned one. */
+export interface ParsedDepend {
+    name: string;
+    relation?: '>=' | '>' | '<=' | '<' | '=';
+    version?: string;
+}
+/** `gjs >= 1.86` → its parts. Both packers need this; only the spelling differs. */
+export declare function parseDepend(depend: string): ParsedDepend;
+/**
+ * Format a dependency for `Depends:`.
+ *
+ * dpkg puts the bound in parentheses and spells strict inequality `<<`/`>>` —
+ * bare `<`/`>` are deprecated aliases for `<=`/`>=`, so emitting them means the
+ * opposite of what it reads like.
+ */
+export declare function formatDebDepend(depend: string): string;
+/** The namespaces the table knows — exported so the unit tests can assert on the set. */
+export declare function knownNamespaces(): string[];