@gjsify/cli 0.49.0 → 0.50.0

package/lib/utils/ship/formats.js

@@ -450,7 +450,21 @@ export const FORMATS = {
         // is a download: it lands in a browser's downloads folder beside other
         // files, so it carries the version and the arch, and it avoids the spaces
         // a display name may contain.
-        fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.${archLabel}.zip`,
+        //
+        // AND THE OPERATING SYSTEM, which the extension does not name. Every other
+        // row's suffix names exactly one platform — `.deb`, `.rpm`, `.flatpak`,
+        // `.dmg`, `.msi` — and `.zip` names none, so this row and `windows-dir-zip`
+        // are the only two artifacts in the table a user cannot tell apart by
+        // looking at them. Before this token they were separated by nothing but a
+        // coincidence between two unrelated arch tables (`MACOS_ARCH` maps x64 to
+        // `x86_64`, `WINDOWS_ARCH` to `x64`), which put a bare `…-1.arm64.zip` on a
+        // release page beside a Windows zip with no way to choose — and would have
+        // had the two formats silently overwrite each other in `ship/out/` the day
+        // a Windows/arm64 row became possible, an upstream blocker (#1117) being
+        // all that stood in the way. `macos`, not `darwin`, for the same reason
+        // `MACOS_ARCH` writes `x86_64` rather than `x64`: this label is read by
+        // whoever downloads the file, never by `process.platform`.
+        fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.macos.${archLabel}.zip`,
         artifactKind: 'file',
     },
     // ── macOS (#1354 M4) ─────────────────────────────────────────────────
@@ -661,7 +675,14 @@ export const FORMATS = {
         // pair splits them: this one is a download that lands in a browser's
         // folder beside other files, so it carries the version and the arch and
         // avoids the spaces a display name may contain.
-        fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.${archLabel}.zip`,
+        //
+        // …and the OS, for the reason spelled out on the `macos-app-zip` row it was
+        // copied from: `.zip` is the one container this table puts on more than one
+        // operating system, so it is the one name that has to say which. `windows`
+        // rather than `win32` — the spelling is the user's, like the `x64` this row
+        // keeps because Node's own archives, gvsbuild's assets and the runner label
+        // all use it.
+        fileName: (s, archLabel) => `${s.binaryName}-${s.version}-${s.release}.windows.${archLabel}.zip`,
         artifactKind: 'file',
     },
     // ── The Windows installer (#1354 M5) ─────────────────────────────────

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

@@ -1,2 +1,31 @@
-/** gzip with the header's timestamp zeroed and the OS byte pinned to Unix. */
-export declare function gzipDeterministic(input: Uint8Array): Promise<Uint8Array>;
+/**
+ * gzip with the header's timestamp zeroed and the OS byte pinned to Unix.
+ *
+ * @param level 0-9, or omitted for zlib's default. THE ONLY HONEST WAY TO SET XFL:
+ *   byte 8 of the header records how hard the compressor tried (2 = maximum,
+ *   4 = fastest, 0 = neither), `lintian` reads it to raise
+ *   `changelog-not-compressed-with-max-compression`, and `file` prints it as
+ *   "max compression". Stamping that byte here beside the mtime and OS bytes would
+ *   be a different thing entirely and was rejected for it: mtime and OS are facts
+ *   about the build ENVIRONMENT, which a reproducible build is entitled to
+ *   normalise, while XFL is a statement about the compression actually performed.
+ *   Writing a 2 we had not earned would make the artifact lie to the tool reading
+ *   it. So the level travels down to the compressor instead.
+ *
+ *   AND THE TEMPTATION IS REAL, which is why this is worth writing down: measured
+ *   on gjsify's own `.deb`, the changelog member compressed at the default level
+ *   and at 9 differs in EXACTLY ONE BYTE — position 9, XFL, 0 against 2 — and is
+ *   1152 bytes either way. For this input, stamping the byte would have produced
+ *   the identical artifact. It is identical by coincidence of a small input: over
+ *   this repo's full `CHANGELOG.md` the same two levels differ by thousands of
+ *   bytes. A rule that happens to hold on today's input is not the rule.
+ */
+export declare function gzipDeterministic(input: Uint8Array, level?: number): Promise<Uint8Array>;
+/**
+ * `gzip -9`, the level Debian Policy § 4.4 asks of a packaging changelog.
+ *
+ * Named rather than spelled `9` at the call site so the reason travels with the
+ * number: the `-n` half of Policy's `gzip -9 -n` is what {@link gzipDeterministic}
+ * already does to bytes 4-7.
+ */
+export declare const POLICY_MAX_COMPRESSION = 9;

package/lib/utils/ship/gzip.js

@@ -5,10 +5,54 @@
 // input produce different bytes — which no test notices, because every test
 // compares the DECOMPRESSED content. It is the single most-missed
 // reproducibility bug in package writers, and it costs nothing to close.
+//
+// WHAT "DETERMINISTIC" DOES NOT COVER, measured 2026-09-11 and named here because
+// the function's own name overstates it: the bytes are reproducible for a given
+// HOST, not for a given artifact. `@gjsify/tar`'s gzip runs on the platform's
+// zlib, and the platforms do not ship the same one — Fedora's libz is
+// `zlib-ng-compat` (2.3.3) while Node bundles its own zlib (1.3.2.1-motley). Over
+// this repo's `CHANGELOG.md` (876 192 bytes) at the DEFAULT level they produce
+// 272 003 and 272 000 bytes respectively, so a `.deb` packed under GJS and one
+// packed under Node already differ, today, before any level argument exists.
+// Levels 1-4 differ too, in the other direction (zlib-ng is smaller). Two
+// consequences worth keeping:
+//
+//   * `tests/e2e/ship-from-stage` asserts byte-equality between a direct pack and
+//     a `--from-stage` pack, and it holds because both run on ONE host. It is
+//     structurally blind to this, and a cross-host pack is exactly what
+//     `--from-stage` exists to enable.
+//   * zlib-ng's level 9 is WORSE than its level 8 on large inputs — 277 974 vs
+//     270 255 bytes on the file above, ~2.9 % bigger — which is why `level: 9` is
+//     asked for only where a reader demands it (see below) and not blanket-applied
+//     to the payload tarballs.
+//
+// Ledgered in `status/open-todos.md`; closing it means pinning ONE deflate
+// implementation, which is a larger decision than this file.
 import { gzip } from '@gjsify/tar';
-/** gzip with the header's timestamp zeroed and the OS byte pinned to Unix. */
-export async function gzipDeterministic(input) {
-    const out = await gzip(input);
+/**
+ * gzip with the header's timestamp zeroed and the OS byte pinned to Unix.
+ *
+ * @param level 0-9, or omitted for zlib's default. THE ONLY HONEST WAY TO SET XFL:
+ *   byte 8 of the header records how hard the compressor tried (2 = maximum,
+ *   4 = fastest, 0 = neither), `lintian` reads it to raise
+ *   `changelog-not-compressed-with-max-compression`, and `file` prints it as
+ *   "max compression". Stamping that byte here beside the mtime and OS bytes would
+ *   be a different thing entirely and was rejected for it: mtime and OS are facts
+ *   about the build ENVIRONMENT, which a reproducible build is entitled to
+ *   normalise, while XFL is a statement about the compression actually performed.
+ *   Writing a 2 we had not earned would make the artifact lie to the tool reading
+ *   it. So the level travels down to the compressor instead.
+ *
+ *   AND THE TEMPTATION IS REAL, which is why this is worth writing down: measured
+ *   on gjsify's own `.deb`, the changelog member compressed at the default level
+ *   and at 9 differs in EXACTLY ONE BYTE — position 9, XFL, 0 against 2 — and is
+ *   1152 bytes either way. For this input, stamping the byte would have produced
+ *   the identical artifact. It is identical by coincidence of a small input: over
+ *   this repo's full `CHANGELOG.md` the same two levels differ by thousands of
+ *   bytes. A rule that happens to hold on today's input is not the rule.
+ */
+export async function gzipDeterministic(input, level) {
+    const out = await gzip(input, level === undefined ? undefined : { level });
     if (out.byteLength < 10 || out[0] !== 0x1f || out[1] !== 0x8b) {
         throw new Error('gjsify ship: internal error — gzip did not produce a gzip stream.');
     }
@@ -19,3 +63,11 @@ export async function gzipDeterministic(input) {
     out[9] = 3;
     return out;
 }
+/**
+ * `gzip -9`, the level Debian Policy § 4.4 asks of a packaging changelog.
+ *
+ * Named rather than spelled `9` at the call site so the reason travels with the
+ * number: the `-n` half of Policy's `gzip -9 -n` is what {@link gzipDeterministic}
+ * already does to bytes 4-7.
+ */
+export const POLICY_MAX_COMPRESSION = 9;

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

@@ -67,11 +67,39 @@ export declare function planOverlay(settings: ShipSettings, format: FormatDescri
  */
 export declare function assertOverlayIsLicensed(formatId: FormatId, binaryName: string, overlay: readonly StagedFile[]): void;
 /**
- * The hicolor subdirectory for an icon: `scalable` for SVG, otherwise the
- * pixel size read from a `<n>x<n>` path component or a trailing number in the
- * filename.
+ * Whether an icon belongs in the theme's SYMBOLIC context rather than at a size.
+ *
+ * `symbolic` is a directory of its own in a hicolor theme and NOT a size value.
+ * Measured in `refs/adwaita-icon-theme/index.theme`, which lists `symbolic/apps`
+ * in `Directories=` beside `scalable/apps` and `16x16/apps` and gives it its own
+ * section — `Context=Applications`, `Size=16`, `MinSize=8`, `MaxSize=512`,
+ * `Type=Scalable` — against the scalable row's `Size=128`. The freedesktop icon
+ * theme specification has no notion of `symbolic` at all: a theme expresses it by
+ * giving the directory a section, which is exactly why reading the EXTENSION
+ * cannot see it, and why this question has to be asked before the size one.
+ *
+ * TWO SIGNALS, the same pair `iconThemeDir` already reads for a size: the
+ * directory an author put the file in, and the name they gave it. GTK resolves a
+ * symbolic icon by the `-symbolic` name suffix, so an author who wrote the name
+ * has said as much as one who wrote the path.
+ *
+ * SVG ONLY, because the symbolic directory is declared `Type=Scalable`: the
+ * raster form GTK's own `gtk-encode-symbolic-svg` produces
+ * (`<name>-symbolic.symbolic.png`) is installed at a SIZE instead. So a PNG keeps
+ * answering the size question, and one that cannot answer it stays refused rather
+ * than quietly becoming a scalable icon that does not scale.
+ */
+export declare function isSymbolicIcon(iconPath: string): boolean;
+/**
+ * The hicolor subdirectory for an icon: the `symbolic` CONTEXT, else `scalable`
+ * for an SVG, else the pixel size read from a `<n>x<n>` path component or a
+ * trailing number in the filename.
+ *
+ * Named for the theme DIRECTORY rather than a size from the moment the first of
+ * those answers stopped being one: `iconSizeDir` returning `symbolic` would be a
+ * name every caller has to read past.
  */
-export declare function iconSizeDir(iconPath: string): string;
+export declare function iconThemeDir(iconPath: string): string;
 /**
  * A native module inside the payload has to keep its executable bit.
  *

package/lib/utils/ship/plan.js

@@ -3,7 +3,7 @@
 // as `utils/copy-targets.ts`, and for the same reason: a stager that discovers
 // its own inputs can only be tested by building a real project.
 import { renderDebianChangelog } from './changelog.js';
-import { gzipDeterministic } from './gzip.js';
+import { gzipDeterministic, POLICY_MAX_COMPRESSION } from './gzip.js';
 import { renderMimePackage } from './mime.js';
 import { SHARE } from './share-dirs.js';
 import { basename, extname, posix } from 'node:path';
@@ -174,12 +174,19 @@ export async function planOverlay(settings, format, inputs) {
     // gzip performed on the packing host would put a second compressor's output in
     // an artifact whose every other byte came from the first. `gzipDeterministic`
     // zeroes the header stamp for the usual reason (utils/ship/gzip.ts).
+    //
+    // It is also the one gzip member in the artifact whose bytes cannot vary with
+    // the packing host, for the same reason: the two hosts' zlibs disagree (that
+    // file's header measurement), and this member is compressed once, here.
     if (format.changelogDest !== undefined) {
         const changelog = renderDebianChangelog(settings, inputs.changelogText, inputs.mtime);
         files.push({
             path: format.changelogDest(settings.binaryName),
             mode: 0o644,
-            source: { kind: 'bytes', data: await gzipDeterministic(new TextEncoder().encode(changelog)) },
+            source: {
+                kind: 'bytes',
+                data: await gzipDeterministic(new TextEncoder().encode(changelog), POLICY_MAX_COMPRESSION),
+            },
         });
     }
     return files;
@@ -233,19 +240,27 @@ function renderDebianCopyright(settings, licenseText) {
  * Icons land in the hicolor theme, named after the app id — that name is what
  * the desktop entry's `Icon=` and the MetaInfo `<id>` both point at, so a file
  * keeping its source basename installs an icon nothing ever looks up.
+ *
+ * A SYMBOLIC icon keeps the `-symbolic` half of that name, and for the same
+ * reason rather than as an exception: the name GTK resolves a symbolic icon by
+ * is `<app id>-symbolic`, so renaming the file to the bare id installs an icon
+ * nothing ever looks up — one sentence, applied to both lookups.
  */
 function planIcons(settings) {
     const out = [];
     const seen = new Map();
     for (const icon of settings.iconFiles) {
         const ext = extname(icon);
-        const dir = iconSizeDir(icon);
-        const path = `${SHARE.icons}/${dir}/apps/${settings.appId}${ext}`;
+        const dir = iconThemeDir(icon);
+        const name = isSymbolicIcon(icon) ? `${settings.appId}-symbolic` : settings.appId;
+        const path = `${SHARE.icons}/${dir}/apps/${name}${ext}`;
         const previous = seen.get(path);
         if (previous !== undefined) {
             throw new Error(`gjsify ship: ${icon} and ${previous} both install as ${path}. ` +
-                'Icon size is read from the path (`.../128x128/...`) or the filename (`icon-128.png`); ' +
-                'give them distinguishable sizes or point `gjsify.ship.icon` at a single file.');
+                'An icon is keyed on its context and its size: `symbolic` is read from a `symbolic/` ' +
+                'path component or a `-symbolic` filename, the size from the path (`.../128x128/...`) ' +
+                'or the filename (`icon-128.png`). Give them distinguishable sizes, or point ' +
+                '`gjsify.ship.icon` at a single file.');
         }
         seen.set(path, icon);
         out.push({ path, mode: 0o644, source: { kind: 'file', path: icon } });
@@ -253,11 +268,47 @@ function planIcons(settings) {
     return out;
 }
 /**
- * The hicolor subdirectory for an icon: `scalable` for SVG, otherwise the
- * pixel size read from a `<n>x<n>` path component or a trailing number in the
- * filename.
+ * Whether an icon belongs in the theme's SYMBOLIC context rather than at a size.
+ *
+ * `symbolic` is a directory of its own in a hicolor theme and NOT a size value.
+ * Measured in `refs/adwaita-icon-theme/index.theme`, which lists `symbolic/apps`
+ * in `Directories=` beside `scalable/apps` and `16x16/apps` and gives it its own
+ * section — `Context=Applications`, `Size=16`, `MinSize=8`, `MaxSize=512`,
+ * `Type=Scalable` — against the scalable row's `Size=128`. The freedesktop icon
+ * theme specification has no notion of `symbolic` at all: a theme expresses it by
+ * giving the directory a section, which is exactly why reading the EXTENSION
+ * cannot see it, and why this question has to be asked before the size one.
+ *
+ * TWO SIGNALS, the same pair `iconThemeDir` already reads for a size: the
+ * directory an author put the file in, and the name they gave it. GTK resolves a
+ * symbolic icon by the `-symbolic` name suffix, so an author who wrote the name
+ * has said as much as one who wrote the path.
+ *
+ * SVG ONLY, because the symbolic directory is declared `Type=Scalable`: the
+ * raster form GTK's own `gtk-encode-symbolic-svg` produces
+ * (`<name>-symbolic.symbolic.png`) is installed at a SIZE instead. So a PNG keeps
+ * answering the size question, and one that cannot answer it stays refused rather
+ * than quietly becoming a scalable icon that does not scale.
+ */
+export function isSymbolicIcon(iconPath) {
+    if (extname(iconPath).toLowerCase() !== '.svg')
+        return false;
+    if (/(?:^|[\\/])symbolic[\\/]/.test(iconPath))
+        return true;
+    return basename(iconPath, extname(iconPath)).endsWith('-symbolic');
+}
+/**
+ * The hicolor subdirectory for an icon: the `symbolic` CONTEXT, else `scalable`
+ * for an SVG, else the pixel size read from a `<n>x<n>` path component or a
+ * trailing number in the filename.
+ *
+ * Named for the theme DIRECTORY rather than a size from the moment the first of
+ * those answers stopped being one: `iconSizeDir` returning `symbolic` would be a
+ * name every caller has to read past.
  */
-export function iconSizeDir(iconPath) {
+export function iconThemeDir(iconPath) {
+    if (isSymbolicIcon(iconPath))
+        return 'symbolic';
     if (extname(iconPath).toLowerCase() === '.svg')
         return 'scalable';
     const square = /(?:^|[\\/])(\d{1,4})x\1(?:[\\/]|$)/.exec(iconPath);

package/lib/utils/simple-command.d.ts

@@ -1,3 +1,18 @@
+export interface TokenizeOptions {
+    /**
+     * Accept an unquoted `*`/`?` as an ordinary token character.
+     *
+     * Off by default, and the default is about EXECUTION: a caller that RUNS
+     * the tokens must not pass `*.tsbuildinfo` through unexpanded, because the
+     * shell it replaces would have expanded it first. A caller that only READS
+     * the targets — `utils/package-inputs.ts`, asking which paths a package
+     * declares it produces — wants the pattern itself, and `gjsify clear`
+     * expands the same two characters in its own last segment anyway
+     * (`utils/clear-targets.ts`). Nothing else moves: every operator,
+     * substitution, brace and tilde still returns `null`.
+     */
+    allowGlobs?: boolean;
+}
 /**
  * Tokenize `cmd`, or return `null` if the string contains anything the shell
  * would treat specially — operators (`&& | ; < > &`), substitutions (`$(...)` /
@@ -7,10 +22,10 @@
  * single literal token, exactly as the shell would hand it to `gjsify` (which
  * does its own glob expansion).
  */
-export declare function tokenizeSimpleCommand(cmd: string): string[] | null;
+export declare function tokenizeSimpleCommand(cmd: string, options?: TokenizeOptions): string[] | null;
 /**
  * The argv of a script that is a single `gjsify <subcommand> …` command — i.e.
  * the tokens after `gjsify` — or `null` when it is anything else. `null` is the
  * signal to hand the literal to a shell.
  */
-export declare function gjsifyCommandArgv(literal: string): string[] | null;
+export declare function gjsifyCommandArgv(literal: string, options?: TokenizeOptions): string[] | null;

package/lib/utils/simple-command.js

@@ -6,6 +6,10 @@
 // deliberately conservative in ONE direction — a `null` costs the caller its
 // fast path, a wrong token list would run a different command than the script
 // says.
+/** Characters that make a string something only a shell may execute. */
+const SHELL_SPECIAL = '|&;<>`$()\\\n\r*?{}[]~#!';
+/** The same set minus `*` and `?` — see {@link TokenizeOptions.allowGlobs}. */
+const SHELL_SPECIAL_ALLOWING_GLOBS = SHELL_SPECIAL.replace('*', '').replace('?', '');
 /**
  * Tokenize `cmd`, or return `null` if the string contains anything the shell
  * would treat specially — operators (`&& | ; < > &`), substitutions (`$(...)` /
@@ -15,7 +19,8 @@
  * single literal token, exactly as the shell would hand it to `gjsify` (which
  * does its own glob expansion).
  */
-export function tokenizeSimpleCommand(cmd) {
+export function tokenizeSimpleCommand(cmd, options = {}) {
+    const special = options.allowGlobs === true ? SHELL_SPECIAL_ALLOWING_GLOBS : SHELL_SPECIAL;
     const tokens = [];
     let cur = '';
     let has = false;
@@ -53,7 +58,7 @@ export function tokenizeSimpleCommand(cmd) {
             }
             continue;
         }
-        if ('|&;<>`$()\\\n\r*?{}[]~#!'.includes(c))
+        if (special.includes(c))
             return null;
         cur += c;
         has = true;
@@ -69,8 +74,8 @@ export function tokenizeSimpleCommand(cmd) {
  * the tokens after `gjsify` — or `null` when it is anything else. `null` is the
  * signal to hand the literal to a shell.
  */
-export function gjsifyCommandArgv(literal) {
-    const tokens = tokenizeSimpleCommand(literal);
+export function gjsifyCommandArgv(literal, options = {}) {
+    const tokens = tokenizeSimpleCommand(literal, options);
     if (!tokens || tokens.length < 2 || tokens[0] !== 'gjsify')
         return null;
     return tokens.slice(1);

package/package.json

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