@gjsify/cli 0.39.0 → 0.41.0

package/lib/utils/prune-prefix.js

@@ -0,0 +1,333 @@
+// Remove what an install prefix holds that THIS host cannot use.
+//
+// An install prefix is a write-only union today: `applyPlatformFilter` keeps a
+// foreign-platform package from being installed, and nothing ever removes one that
+// an EARLIER install placed. Measured on a workstation whose user-global prefix was
+// created in May and whose CLI was current: 638 MB, of which `@rolldown` alone was
+// 258 MB across sixteen platform bindings on a host that can load exactly one.
+//
+// The residue is ACCRETION, not a live filter defect, and the on-disk versions are
+// what prove it: the foreign `@rolldown/binding-*` dirs were a minor version behind
+// the `rolldown` that pins all of them, and every foreign `@gjsify/*-<os>-<arch>`
+// was at the release that first SHIPPED the filter. They were written by the
+// previous CLI, during the self-update that installed the fix. A filter cannot
+// remove what predates it, which is why this exists as its own pass.
+//
+// ## What this is allowed to decide
+//
+// One rule, and it is a pure manifest read: npm's own `os`/`cpu`/`libc` fields,
+// through the SAME `checkPlatform` the installer filters with — so a pruned prefix
+// converges on what a fresh install would have placed, rather than on this module's
+// opinion. A package that declares nothing is never touched: `@rolldown/binding-
+// wasm32-wasi` is unusable here and says so nowhere, and guessing from its name is
+// how a prune starts deleting things it cannot justify.
+//
+// Reachability ("nothing installed points at this any more") would catch that one
+// and more, but it needs a record of what the prefix was ASSEMBLED FROM, which no
+// prefix carries yet. Uncertain means keep — see ADR 0025 and
+// `status/open-todos.md`.
+import { existsSync, lstatSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { checkPlatform, declaresPlatform, describePlatformTarget, readPlatformOverrides, } from './platform-check.js';
+/** Directory entries under `node_modules` that are never packages. */
+function isReservedEntry(name) {
+    // `.bin` holds launchers, `.gjsify-install-lock` is the LIVE cross-process lock
+    // directory — removing it mid-install would hand the prefix to a second writer.
+    return name.startsWith('.');
+}
+function readManifest(dir) {
+    try {
+        const raw = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+        const platform = {
+            os: raw.os,
+            cpu: raw.cpu,
+            libc: raw.libc,
+        };
+        return {
+            name: typeof raw.name === 'string' ? raw.name : undefined,
+            version: typeof raw.version === 'string' ? raw.version : undefined,
+            platform: declaresPlatform(platform) ? platform : undefined,
+        };
+    }
+    catch {
+        // An unreadable or half-written manifest declares nothing, which makes the
+        // package un-prunable by the only rule this module has. That is the safe
+        // direction: the one thing worse than 638 MB of residue is deleting a
+        // package because its manifest could not be parsed.
+        return null;
+    }
+}
+function collect(nodeModules, out) {
+    let entries;
+    try {
+        entries = readdirSync(nodeModules, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (isReservedEntry(entry.name))
+            continue;
+        const full = join(nodeModules, entry.name);
+        if (entry.name.startsWith('@')) {
+            let scoped;
+            try {
+                scoped = readdirSync(full, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const inner of scoped) {
+                if (isReservedEntry(inner.name))
+                    continue;
+                addPackage(join(full, inner.name), out);
+            }
+            continue;
+        }
+        addPackage(full, out);
+    }
+}
+function addPackage(dir, out) {
+    let linked = false;
+    try {
+        linked = lstatSync(dir).isSymbolicLink();
+    }
+    catch {
+        return;
+    }
+    const manifest = readManifest(dir);
+    out.push({
+        name: manifest?.name ?? dir,
+        version: manifest?.version ?? '0.0.0',
+        dir,
+        linked,
+        platform: manifest?.platform,
+    });
+    // A linked package is the user's own source tree — its `node_modules` is not
+    // this prefix's to prune.
+    if (!linked)
+        collect(join(dir, 'node_modules'), out);
+}
+/** Every package directory under `<prefix>/node_modules`, at any depth. */
+export function scanPrefix(prefix) {
+    const out = [];
+    collect(join(prefix, 'node_modules'), out);
+    return out;
+}
+/**
+ * The packages `target` cannot use. Pure — no filesystem, no `process.*` — so every
+ * OS/arch/libc branch is decidable from any host.
+ */
+export function planPlatformPrune(pkgs, target) {
+    const entries = [];
+    for (const pkg of pkgs) {
+        if (pkg.linked || !pkg.platform)
+            continue;
+        const verdict = checkPlatform(pkg.platform, target);
+        if (!verdict.ok)
+            entries.push({ pkg, bytes: 0, verdict });
+    }
+    return entries;
+}
+/** Apparent size of a directory tree — what the files claim, not what the block device spent. */
+export function dirBytes(dir) {
+    let total = 0;
+    const stack = [dir];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+            }
+            else if (entry.isFile()) {
+                try {
+                    total += statSync(full).size;
+                }
+                catch {
+                    // A file that vanished mid-walk contributes nothing; a size is a
+                    // report, and refusing to produce one over a race would be worse.
+                }
+            }
+        }
+    }
+    return total;
+}
+export function planPrune(opts) {
+    const pkgs = scanPrefix(opts.prefix);
+    const entries = planPlatformPrune(pkgs, opts.target);
+    for (const entry of entries)
+        entry.bytes = dirBytes(entry.pkg.dir);
+    return {
+        prefix: opts.prefix,
+        target: opts.target,
+        scanned: pkgs.length,
+        entries,
+        bytes: entries.reduce((sum, e) => sum + e.bytes, 0),
+    };
+}
+/**
+ * Remove a plan's entries.
+ *
+ * `remove` is injected so the failure path is testable without a filesystem that
+ * can fail on demand. Nothing here throws: this runs as housekeeping at the end of
+ * an install, and an install that already succeeded must not be reported as failed
+ * because a directory could not be unlinked.
+ */
+export function executePrune(plan, opts = {}) {
+    const removed = [];
+    const failed = [];
+    const binLinks = [];
+    // `maxRetries` mirrors the installer's own removal: on Windows a handle held by
+    // a virus scanner or an indexer makes the first unlink fail and the third work.
+    const remove = opts.remove ?? ((dir) => rmSync(dir, { recursive: true, force: true, maxRetries: 10 }));
+    if (!opts.dryRun) {
+        for (const entry of plan.entries) {
+            try {
+                remove(entry.pkg.dir);
+                removed.push(entry);
+            }
+            catch (err) {
+                failed.push({ entry, error: err.message });
+            }
+        }
+        binLinks.push(...pruneDeadBinLinks(plan.prefix));
+    }
+    return {
+        plan,
+        removed,
+        failed,
+        bytes: removed.reduce((sum, e) => sum + e.bytes, 0),
+        binLinks,
+    };
+}
+/**
+ * Drop `.bin` entries that are SYMLINKS whose target is gone.
+ *
+ * Only symlinks, and only dangling ones: that is the case where deadness is
+ * provable from the filesystem alone. A `.bin` entry that is a real file may be a
+ * launcher script this prefix still needs, and deciding that would mean reading it —
+ * a second, weaker rule for a few hundred bytes.
+ */
+function pruneDeadBinLinks(prefix) {
+    const binDir = join(prefix, 'node_modules', '.bin');
+    const dropped = [];
+    let entries;
+    try {
+        entries = readdirSync(binDir, { withFileTypes: true });
+    }
+    catch {
+        return dropped;
+    }
+    for (const entry of entries) {
+        const full = join(binDir, entry.name);
+        try {
+            if (!lstatSync(full).isSymbolicLink())
+                continue;
+            if (existsSync(full))
+                continue;
+            unlinkSync(full);
+            dropped.push(entry.name);
+        }
+        catch {
+            // Same reasoning as `executePrune`: housekeeping never fails the caller.
+        }
+    }
+    return dropped;
+}
+function humanBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KB', 'MB', 'GB'];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    return `${value.toFixed(1)} ${units[unit]}`;
+}
+/** How many entries a non-verbose report lists before summarising the rest. */
+const REPORT_HEAD = 10;
+export function formatPruneReport(result, opts) {
+    const { plan } = result;
+    const lines = [
+        `${plan.prefix} · target ${describePlatformTarget(plan.target)} · scanned ${plan.scanned} package(s)`,
+    ];
+    if (plan.entries.length === 0) {
+        // Not "every package declares a platform this host can use": most declare
+        // none at all, and saying otherwise reports a check that did not happen.
+        lines.push('nothing to prune — no installed package declares a platform this target cannot use.');
+        return lines.join('\n');
+    }
+    const shown = opts.verbose ? plan.entries : plan.entries.slice(0, REPORT_HEAD);
+    for (const entry of shown) {
+        const required = JSON.stringify(entry.verdict.required);
+        lines.push(`  ${entry.pkg.name}@${entry.pkg.version}  ${humanBytes(entry.bytes)}  requires ${required}`);
+    }
+    if (shown.length < plan.entries.length) {
+        lines.push(`  … and ${plan.entries.length - shown.length} more (--verbose to list them)`);
+    }
+    // The byte figure is APPARENT size, summed from the files themselves. `du`
+    // reports allocated blocks and will disagree; saying so here is cheaper than
+    // the bug report that difference otherwise produces.
+    lines.push(opts.dryRun
+        ? `would free ${humanBytes(plan.bytes)} across ${plan.entries.length} package(s) (apparent size)`
+        : `freed ${humanBytes(result.bytes)} across ${result.removed.length} package(s) (apparent size)`);
+    if (result.binLinks.length > 0) {
+        lines.push(`removed ${result.binLinks.length} dangling .bin link(s): ${result.binLinks.join(', ')}`);
+    }
+    for (const f of result.failed) {
+        lines.push(`FAILED ${f.entry.pkg.name}: ${f.error}`);
+    }
+    return lines.join('\n');
+}
+/** Why an automatic pass declined to run, or null when it may proceed. */
+export function automaticPruneRefusal(env, immutable) {
+    // THE data-loss guard. `--os/--cpu/--libc` are legal on `gjsify install -g`, and
+    // they reach here as npm config keys. Pruning against a target the USER TYPED
+    // would make `gjsify install -g foo --os=darwin` delete every linux package in
+    // the real shared prefix — the engine set, the bundler bindings, the CLI's own.
+    // An explicit `gjsify prune --os=darwin` stays legal; it is a request, not a
+    // side effect.
+    if (Object.keys(readPlatformOverrides(env)).length > 0) {
+        return 'the platform target was overridden on the command line';
+    }
+    // `--immutable` promises the tree is not modified. Resolution-only would be a
+    // defensible reading, but it is not the one the flag's users have, and
+    // `ensureProjectGjsEngine` already declines under it for the same reason.
+    if (immutable)
+        return '--immutable';
+    return null;
+}
+/**
+ * The automatic pass: prune what this install would not have placed, report one
+ * line, and never fail the install that called it.
+ */
+export function pruneAfterInstall(prefix, target, opts = {}) {
+    try {
+        const refusal = automaticPruneRefusal(opts.env ?? process.env, opts.immutable ?? false);
+        if (refusal)
+            return;
+        const plan = planPrune({ prefix, target });
+        if (plan.entries.length === 0)
+            return;
+        const result = executePrune(plan);
+        if (result.removed.length === 0)
+            return;
+        const hint = opts.hint ? ` (${opts.hint} to review)` : '';
+        console.log(`gjsify: pruned ${result.removed.length} package(s) this host cannot use, ` +
+            `freeing ${humanBytes(result.bytes)}${hint}`);
+    }
+    catch (err) {
+        if (process.env.GJSIFY_DEBUG)
+            console.error(`gjsify: prune skipped — ${err.message}`);
+    }
+}

package/lib/utils/publish-headers.d.ts

@@ -39,3 +39,16 @@ export interface PublishHeaderOptions {
  */
 export declare function buildPublishHeaders(url: string, opts: PublishHeaderOptions): Record<string, string>;
 export declare function cliVersion(): string;
+/**
+ * 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 declare function cliPackageDir(): string | null;

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[];