@gjsify/cli 0.52.0 → 0.54.0

package/lib/utils/run-gjs.d.ts

@@ -6,7 +6,7 @@ import { type SpawnCompletionContract } from './spawn.js';
  * variable is set is host-dependent (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH`) — see
  * `buildNativeEnv`.
  */
-export declare function computeNativeEnvForBundle(bundlePath: string, cwd?: string, inherited?: Record<string, string | undefined>): {
+export declare function computeNativeEnvForBundle(bundlePath: string, cwd?: string, inherited?: Record<string, string | undefined>, extraRoots?: readonly string[]): {
     env: NativeEnv;
     envPrefix: string;
 };
@@ -41,5 +41,19 @@ export interface RunGjsBundleOptions {
      * (`utils/node-script.ts`).
      */
     quiet?: boolean;
+    /**
+     * Do not add `gjs exited with code N` to a failing child's own output. For a
+     * transparent runner (`gjsify exec`) a non-zero exit is often an ANSWER — `semver
+     * -r '>2' 1.0.0` exits 1 to say "no match" — and the child's code is re-raised
+     * either way.
+     */
+    quietExit?: boolean;
+    /**
+     * More directories to look for native `@gjsify/*` prebuilds in, after the cwd and the
+     * bundle's own tree. `gjsify exec` passes the running CLI's: a rebuilt bin takes its
+     * polyfills from beside the CLI, so their typelibs live there too — web-ext's rebuild
+     * died at load with `Typelib file for namespace 'GjsifyHttpSoupBridge' … not found`.
+     */
+    nativeRoots?: readonly string[];
 }
 export declare function runGjsBundle(bundlePath: string, extraArgs: string[] | undefined, options: RunGjsBundleOptions): Promise<void>;

package/lib/utils/run-gjs.js

@@ -21,12 +21,20 @@ import { captureNativeBacktrace, createHangWatchdog, formatHangReport, hangGrace
  * variable is set is host-dependent (`LD_LIBRARY_PATH` / `DYLD_LIBRARY_PATH` / `PATH`) — see
  * `buildNativeEnv`.
  */
-export function computeNativeEnvForBundle(bundlePath, cwd = process.cwd(), inherited = process.env) {
+export function computeNativeEnvForBundle(bundlePath, cwd = process.cwd(), inherited = process.env, extraRoots = []) {
     const resolvedBundle = resolve(bundlePath);
-    const cwdPackages = detectNativePackages(cwd);
-    const bundlePackages = detectNativePackages(dirname(resolvedBundle));
-    const seen = new Set(cwdPackages.map((p) => p.name));
-    const nativePackages = [...cwdPackages, ...bundlePackages.filter((p) => !seen.has(p.name))];
+    // First root wins per package name: the project, then the bundle's own tree, then
+    // whatever the caller adds (see `RunGjsBundleOptions.nativeRoots`).
+    const nativePackages = [];
+    const seen = new Set();
+    for (const root of [cwd, dirname(resolvedBundle), ...extraRoots]) {
+        for (const pkg of detectNativePackages(root)) {
+            if (seen.has(pkg.name))
+                continue;
+            seen.add(pkg.name);
+            nativePackages.push(pkg);
+        }
+    }
     // `inherited` feeds BOTH halves — composition and comparison. Split them and the win32
     // branch disagrees with itself: `buildNativeEnv` writes the library variable back under
     // the host's own spelling (`Path` in a stock env block), so a comparison keyed on the
@@ -58,7 +66,7 @@ function safeMkdtemp() {
     }
 }
 export async function runGjsBundle(bundlePath, extraArgs = [], options) {
-    const { env: nativeEnv, envPrefix } = computeNativeEnvForBundle(bundlePath);
+    const { env: nativeEnv, envPrefix } = computeNativeEnvForBundle(bundlePath, process.cwd(), process.env, options.nativeRoots);
     // The breadcrumb `@gjsify/unit` writes what it is running into, and this process polls —
     // the only way a bundle that has stopped turning its main loop can still say which test it
     // died in. Anything that is not a unit run never writes the file, so the watchdog stays
@@ -149,7 +157,8 @@ export async function runGjsBundle(bundlePath, extraArgs = [], options) {
     if (hung)
         return failed(result.code ?? 1);
     if (result.code !== 0) {
-        console.error(`gjs exited with ${describeExit(result)}`);
+        if (!options.quietExit)
+            console.error(`gjs exited with ${describeExit(result)}`);
         return failed(result.code ?? 1);
     }
     // See RunGjsBundleOptions.exitOnSuccess — terminal callers opt in,

package/lib/utils/run-node.d.ts

@@ -26,6 +26,8 @@ export interface RunNodeBundleOptions {
     exitOnSuccess?: boolean;
     /** Suppress the `$ <env> node …` echo — see `RunGjsBundleOptions.quiet`. */
     quiet?: boolean;
+    /** Leave a failing child's output alone — see `RunGjsBundleOptions.quietExit`. */
+    quietExit?: boolean;
 }
 /**
  * Run a `--app node` bundle on Node.js with the native typelib env set (same detection as

package/lib/utils/run-node.js

@@ -148,7 +148,8 @@ export async function runRuntimeBundle(runtime, bundlePath, extraArgs = [], opti
         return failed(1);
     }
     if (result.code !== 0) {
-        console.error(`${runtime} exited with ${describeExit(result)}`);
+        if (!options.quietExit)
+            console.error(`${runtime} exited with ${describeExit(result)}`);
         return failed(result.code ?? 1);
     }
     if (options.exitOnSuccess)

package/lib/utils/runtimes.js

@@ -6,13 +6,14 @@
 // runtime→build-target mapping and `availableRuntimes()` live in ONE place instead
 // of a per-example copy.
 //
-// Intentionally PURE (only `node:child_process` and the side-effect-free
-// `@gjsify/rolldown-plugin-gjsify/runtime` host detector, no `gi://` or native
-// imports) so an external example can deep-import it from the installed CLI
-// (`@gjsify/cli/lib/utils/runtimes.js`) without pulling in the whole bundler — the
-// same deep-import precedent as `@gjsify/cli/lib/utils/run-gjs.js`.
-import { execFileSync } from 'node:child_process';
+// Intentionally PURE (only `node:child_process`, `./spawn.js`'s Windows command
+// rewrite and the side-effect-free `@gjsify/rolldown-plugin-gjsify/runtime` host
+// detector, no `gi://` or native imports) so an external example can deep-import
+// it from the installed CLI (`@gjsify/cli/lib/utils/runtimes.js`) without pulling
+// in the whole bundler — the same deep-import precedent as `@gjsify/cli/lib/utils/run-gjs.js`.
+import { spawnSync } from 'node:child_process';
 import { hostRuntime } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { toSpawnable } from './spawn.js';
 /** All runtimes, in canonical order (gjs first — it is the reference). */
 export const EXAMPLE_RUNTIMES = ['gjs', 'node', 'bun', 'deno'];
 /**
@@ -57,13 +58,13 @@ export function requiresGjsSystemDeps(runtime) {
 }
 /** Whether `<probe> --version` succeeds (i.e. the runtime binary is on PATH). */
 export function isRuntimeOnPath(probe) {
-    try {
-        execFileSync(probe, ['--version'], { stdio: 'ignore', timeout: 15000 });
-        return true;
-    }
-    catch {
-        return false;
-    }
+    const inv = toSpawnable(probe, ['--version']);
+    const r = spawnSync(inv.cmd, inv.args, {
+        stdio: 'ignore',
+        timeout: 15000,
+        windowsVerbatimArguments: inv.windowsVerbatimArguments,
+    });
+    return !r.error && r.status === 0;
 }
 /**
  * Whether a specific runtime is runnable here. The HOST runtime needs no PATH probe

package/lib/utils/ship/app-runtime.d.ts

@@ -102,8 +102,8 @@ export interface ResolvedNodeGiPackage {
  * NOT the published tarball. `files` in node-gi's manifest also lists `src/`,
  * `binding.gyp` and `scripts/install.mjs` — the inputs to `node-gyp`, which a
  * `.app` never runs — and the `.d.ts` declarations, which nothing inside a bundle
- * compiles against. And it lists `prebuilds/`, which this module stages into
- * `Contents/Frameworks` instead, where a `.app` keeps loadable code.
+ * compiles against. And it lists `prebuilds/`, which this module stages under
+ * `Layout.dirs().native`, the directory a `.app` keeps loadable code in.
  *
  * So the rule is what `require('@gjsify/node-gi/<subpath>')` can REACH:
  * `package.json` (the `exports` map is what resolves every subpath), every `.js`
@@ -120,15 +120,17 @@ export declare function resolveNodeGiPackage(options?: ResolveRuntimeOptions): R
  * literals, so the paths the launcher exports and the paths the stager writes
  * cannot drift: they are computed here once and both callers read this result.
  *
- * `Contents/Frameworks/node-gi/prebuilds/<target>/` is node-gi's OWN sibling
- * layout reproduced verbatim inside `dirs.native`. It is not a naming preference:
+ * `<dirs.native>/node-gi/prebuilds/<target>/` is node-gi's OWN sibling layout
+ * reproduced verbatim inside `Layout.dirs().native` (`Contents/Resources/native`
+ * on a `.app` — `layout.ts`'s darwin row carries why that is not
+ * `Contents/Frameworks`). It is not a naming preference:
  * `resolveGtkRuntimeBundle()` probes `<dir>/lib` and `<dir>/girepository-1.0`,
  * the addon's `@rpath` is `@loader_path/gtk/lib`, and `loaders.cache` addresses
  * each pixbuf loader relative to the bundle toplevel. Reproducing the shape is
  * what makes every one of those relations still true after the copy.
  */
 export interface AppRuntimePaths {
-    /** `<App>.app/Contents/Frameworks/node-gi` — the package root the layout imitates. */
+    /** `<App>.app/Contents/Resources/native/node-gi` — the package root the layout imitates. */
     nodeGiRoot: string;
     /**
      * `<App>.app/Contents/Resources/lib/node_modules/@gjsify/node-gi` — where

package/lib/utils/ship/app-runtime.js

@@ -47,11 +47,14 @@
 // THAT directory — so `prebuildAddonPath()` looks for
 // `…/node_modules/@gjsify/node-gi/prebuilds/<target>/node_gi.node` and
 // `resolveGtkRuntimeBundle()`'s candidate 2 for `…/prebuilds/<target>/gtk`, and
-// neither is where a `.app` may keep loadable code: `Contents/Frameworks` is, and
-// it is what `codesign` now reaches (ADR 0024 § A4) — M6 landed, and
-// `utils/ship/signing.ts` re-signs every Mach-O in the payload by magic number,
-// which is most of this closure. Putting it under `Resources` to save two
-// `export` lines would trade a correct bundle for a shorter launcher.
+// neither is where a `.app` may keep loadable code: `Layout.dirs().native` is, and
+// `utils/ship/signing.ts` re-signs every Mach-O in the payload by magic number
+// (ADR 0024 § A4 — M6 landed), which is most of this closure. What `native` may NOT
+// be is `Contents/Frameworks`: `codesign` reads a version-named DIRECTORY there as
+// a nested bundle and refuses the seal, which is the whole reason this file's
+// output went into `Contents/Resources/native` instead — see `layout.ts`'s darwin
+// row for the measurement and `gjsify ship darwin --sign` for what it used to
+// cost.
 //
 // WHY NOT `gjsify.ship.bundledTypelibs`. Because it FLATTENS. `plan.ts` stages
 // each such file as `posix.join(libDir, 'gi', basename(file))`, and
@@ -210,8 +213,8 @@ function resolveStagedPackage(specifier, options) {
  * NOT the published tarball. `files` in node-gi's manifest also lists `src/`,
  * `binding.gyp` and `scripts/install.mjs` — the inputs to `node-gyp`, which a
  * `.app` never runs — and the `.d.ts` declarations, which nothing inside a bundle
- * compiles against. And it lists `prebuilds/`, which this module stages into
- * `Contents/Frameworks` instead, where a `.app` keeps loadable code.
+ * compiles against. And it lists `prebuilds/`, which this module stages under
+ * `Layout.dirs().native`, the directory a `.app` keeps loadable code in.
  *
  * So the rule is what `require('@gjsify/node-gi/<subpath>')` can REACH:
  * `package.json` (the `exports` map is what resolves every subpath), every `.js`
@@ -252,7 +255,7 @@ export function appRuntimePaths(layout, identity, target) {
         addonPath: posix.join(prebuildDir, NODE_GI_ADDON_FILENAME),
         // `Contents/MacOS`, because that is where a `.app` keeps executables and
         // because `$here` — which the launcher already computes — is then the whole
-        // path expression. `Contents/Frameworks` would work for dyld and would make
+        // path expression. `dirs.native` would work for dyld and would make
         // the launcher walk back up for the one file it execs. On Windows
         // `dirs.launcher` is the program directory itself, so the interpreter lands
         // beside the `.cmd` for the same reason.

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

@@ -89,6 +89,15 @@ export declare function appImageHostRequirements(input: {
     minGjsVersion?: string;
     minNodeVersion?: string;
     namespaces: readonly string[];
+    /**
+     * The subset of {@link namespaces} the bundle marks optional (ADR 0087).
+     *
+     * An AppImage has no `Depends:` field, so "optional" cannot become a package
+     * list here — it becomes WORDING instead. That is not cosmetic: an AppRun user
+     * told a typelib is required and lacking it goes looking for another distro
+     * package, while one told it is optional reads the same sentence correctly.
+     */
+    optionalNamespaces?: readonly string[];
     bundledTypelibs?: readonly string[];
 }): string[];
 /**

package/lib/utils/ship/appimage.js

@@ -204,9 +204,10 @@ export function appDirFor(outRoot) {
  */
 export function appImageHostRequirements(input) {
     const floor = interpreterFloor(input);
+    const optional = new Set(input.optionalNamespaces ?? []);
     return [
         `${input.app} (>= ${floor})`,
-        ...hostProvidedNamespaces(input.namespaces, input.bundledTypelibs).map((ns) => `the ${ns} typelib`),
+        ...hostProvidedNamespaces(input.namespaces, input.bundledTypelibs).map((ns) => optional.has(ns) ? `the ${ns} typelib (optional)` : `the ${ns} typelib`),
     ];
 }
 /**

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

@@ -8,6 +8,16 @@ export interface DebInputs {
     prefix: string;
     /** Already-derived dependency list, in `name`/`name >= version` form. */
     depends: readonly string[];
+    /**
+     * Soft dependencies, rendered as `Recommends:`.
+     *
+     * Debian Policy § 7.2: a recommended package is installed by default and
+     * `--no-install-recommends` is the user's way out. That is what an `&optional`
+     * typelib is (ADR 0087) — the app runs without it and loses a feature — so
+     * putting it in `Depends:` would let an optional integration decide whether
+     * the package installs at all.
+     */
+    recommends?: readonly string[];
     /** Debian architecture (`amd64`, `all`, …). */
     archLabel: string;
     /** Unix seconds stamped into every header. */

package/lib/utils/ship/deb.js

@@ -104,6 +104,13 @@ function renderControl(inputs, installedSize) {
     ];
     if (inputs.depends.length > 0)
         fields.push(['Depends', inputs.depends.map(formatDebDepend).join(', ')]);
+    // After `Depends`, which is the field order dpkg-deb --control writes and the
+    // one `grep '^Depends:'` on a control file assumes. Omitted when empty rather
+    // than written as `Recommends:` with nothing after it — a field with an empty
+    // value is a parse error here, the same reason `formatDebDepend` exists.
+    if (inputs.recommends !== undefined && inputs.recommends.length > 0) {
+        fields.push(['Recommends', inputs.recommends.map(formatDebDepend).join(', ')]);
+    }
     fields.push(['Section', settings.section], ['Priority', 'optional']);
     if (settings.homepage)
         fields.push(['Homepage', settings.homepage]);

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

@@ -43,6 +43,17 @@ export declare function warnAboutNodeFloor(format: DistroFormatId, floor: string
 export interface DependsInputs {
     /** GI namespaces the bundle imports, in `Ns-Version` spelling. */
     namespaces: readonly string[];
+    /**
+     * The subset of {@link namespaces} the bundle declares OPTIONAL (ADR 0087 —
+     * `gi://Ns?version=X&optional`): a `Recommends:` entry, never a `Depends:`.
+     *
+     * Kept as its own list rather than filtered out of {@link namespaces}, because
+     * the AppImage has no package list at all and still has to SAY which of its host
+     * requirements are optional — and because a stage manifest written before the
+     * split carries no such field, where answering "everything is hard" is the safe
+     * direction.
+     */
+    optionalNamespaces?: readonly string[];
     /**
      * Whether the payload installs into `share/icons/hicolor/`.
      *
@@ -112,11 +123,34 @@ export interface DependsInputs {
  */
 export declare function hostProvidedNamespaces(namespaces: readonly string[], bundledTypelibs?: readonly string[]): string[];
 /**
- * The `Depends:` / `Requires:` list for one format.
+ * One format's dependency lists, split by how hard the requirement is.
+ *
+ * `requires` is what an absent package makes the app fail over; `recommends` is what
+ * its absence only costs. A namespace the BUNDLE marked optional (ADR 0087) is the
+ * second kind by declaration — the app's own `check()` degrades — and both `.deb`
+ * and `.rpm` have a field for it, so there is no reason to declare it hard.
+ */
+export interface DerivedDepends {
+    /** `Depends:` / `Requires:` — a package the artifact cannot run without. */
+    requires: string[];
+    /** `Recommends:` — installed by default where the format has such a field. */
+    recommends: string[];
+    /**
+     * Optional namespaces no table row is known for.
+     *
+     * REPORTED, never fatal: a `Recommends:` line for a namespace nobody mapped is
+     * the one case where saying nothing is correct — the app runs without the
+     * typelib either way, which is precisely what the flag declared. The HARD
+     * unmapped case still throws, below.
+     */
+    unmappedOptional: string[];
+}
+/**
+ * The `Depends:` / `Requires:` list for one format, plus its `Recommends:`.
  *
- * @throws when a namespace has no entry in the table — see the module header.
+ * @throws when a HARD namespace has no entry in the table — see the module header.
  */
-export declare function deriveDepends(format: DistroFormatId, inputs: DependsInputs): string[];
+export declare function deriveDepends(format: DistroFormatId, inputs: DependsInputs): DerivedDepends;
 /** One parsed dependency. `relation`/`version` are absent for an unversioned one. */
 export interface ParsedDepend {
     name: string;

package/lib/utils/ship/depends.js

@@ -287,9 +287,9 @@ export function hostProvidedNamespaces(namespaces, bundledTypelibs = []) {
     return [...new Set(namespaces)].sort().filter((ns) => !BUNDLED_TYPELIB.test(ns) && !shipped.has(ns));
 }
 /**
- * The `Depends:` / `Requires:` list for one format.
+ * The `Depends:` / `Requires:` list for one format, plus its `Recommends:`.
  *
- * @throws when a namespace has no entry in the table — see the module header.
+ * @throws when a HARD namespace has no entry in the table — see the module header.
  */
 export function deriveDepends(format, inputs) {
     // The interpreter the launcher execs, and nothing else: a package declares ONE.
@@ -297,17 +297,25 @@ export function deriveDepends(format, inputs) {
     // no system Node, so an artifact for those CARRIES one from
     // `@gjsify/node-runtime-<target>`, and that is the whole reason those three
     // packages exist and this one line is their opposite.
-    const out = inputs.interpreter === 'node'
+    const requires = inputs.interpreter === 'node'
         ? [`${NODE_PACKAGE[format]} >= ${inputs.minNodeVersion ?? DEFAULT_NODE_FLOOR}`]
         : [`gjs >= ${inputs.minGjsVersion ?? DEFAULT_GJS_FLOOR}`];
+    const recommends = [];
+    const optional = new Set(inputs.optionalNamespaces ?? []);
     const unmapped = [];
+    const unmappedOptional = [];
     for (const namespace of hostProvidedNamespaces(inputs.namespaces, inputs.bundledTypelibs)) {
         const entry = lookupTypelib(namespace, inputs.typelibPackages);
         if (entry === undefined) {
-            unmapped.push(namespace);
+            (optional.has(namespace) ? unmappedOptional : unmapped).push(namespace);
             continue;
         }
-        out.push(entry[format]);
+        // A namespace imported both ways is a HARD dependency — one importer asked
+        // for it unguarded — and a package manager field may not name it twice.
+        if (optional.has(namespace) && !requires.includes(entry[format]))
+            recommends.push(entry[format]);
+        else
+            requires.push(entry[format]);
     }
     if (unmapped.length > 0) {
         throw new Error(`gjsify ship: the bundle imports ${unmapped.map((n) => `gi://${n.split('-')[0]}`).join(', ')}, ` +
@@ -323,7 +331,7 @@ export function deriveDepends(format, inputs) {
     // The package that owns `/usr/share/icons/hicolor` — so this follows the icons, not the
     // app/cli distinction that used to stand in for them.
     if (inputs.hasIcons)
-        out.push('hicolor-icon-theme');
+        requires.push('hicolor-icon-theme');
     // The package that ships `glib-compile-schemas`, NOT `gsettings-desktop-schemas`
     // (which ships GNOME's own `org.gnome.desktop.*` schemas and has nothing to
     // do with compiling ours). Measured: `rpm -qf /usr/bin/glib-compile-schemas`
@@ -333,11 +341,15 @@ export function deriveDepends(format, inputs) {
     // `Gio.Settings.new()` aborts the app — an install that succeeds and an app
     // that does not start.
     if (inputs.hasSchemas)
-        out.push(SCHEMA_COMPILER_PACKAGE[format]);
-    out.push(...inputs.extra);
+        requires.push(SCHEMA_COMPILER_PACKAGE[format]);
+    requires.push(...inputs.extra);
     // Set-dedupe keeps first-insertion order, so the interpreter stays first and
     // the list is stable across runs.
-    return [...new Set(out)];
+    return {
+        requires: [...new Set(requires)],
+        recommends: [...new Set(recommends)].filter((name) => !requires.includes(name)),
+        unmappedOptional,
+    };
 }
 /**
  * Resolve a scanned specifier to a table row.

package/lib/utils/ship/gi-namespaces.d.ts

@@ -1,7 +1,23 @@
+/**
+ * What a bundle loads, split by whether the host must provide it.
+ *
+ * `namespaces` is the union — the same answer {@link scanGiNamespaces} has always
+ * given — and `optional` is the subset the artifact itself marks optional. A namespace
+ * in both is still a hard dependency as far as anything else is concerned: the
+ * importer asked for it both ways, and only one of those edges degrades.
+ */
+export interface GiRequirements {
+    /** Every GI namespace the bundle loads, `Ns-Version` where a specifier pins one. */
+    namespaces: string[];
+    /** The subset carrying the bundler's optional marker — absent is not fatal. */
+    optional: string[];
+}
 /**
  * Extract the GI namespaces a bundle imports, as `Ns-Version` when the
  * specifier pins one and bare `Ns` when it does not.
  */
 export declare function scanGiNamespaces(source: string): string[];
+/** {@link scanGiNamespaces}, plus which of them the artifact marks optional (ADR 0087). */
+export declare function scanGiRequirements(source: string): GiRequirements;
 /** `gi://Gtk?version=4.0` → `Gtk-4.0`; `gi://Gtk` → `Gtk`; anything else → null. */
 export declare function parseGiSpecifier(specifier: string): string | null;

package/lib/utils/ship/gi-namespaces.js

@@ -34,6 +34,18 @@
 // `walkModuleAst` answers both questions in ONE pass, and it is the same acorn
 // pass the CLI already uses to compute its own runtime closure — so there is one
 // definition of "what does this file import" rather than two.
+//
+// HARD OR OPTIONAL, since ADR 0087: a `gi://Ns?version=X&optional` import still
+// appears in the emitted file, so this scanner still reports its namespace — and
+// `depends.ts` has to know it may be absent. The discriminator is the marker
+// statement the bundler's own optional shim emits (`GI_OPTIONAL_MARKER`, imported
+// from the plugin that writes it rather than restated here). NOT the `import()`
+// SHAPE, which was the tempting reading of the same file: an app that writes its own
+// `await import('gi://Goa')` without the flag must stay a HARD dependency, and
+// classifying it as optional would move a package the host must have out of its
+// `Depends:` — the failure this whole chain exists to prevent, reached from the other
+// direction.
+import { GI_OPTIONAL_MARKER } from '@gjsify/rolldown-plugin-gjsify';
 import { importedSpecifier, staticStringValue, walkModuleAst, } from '../cli-runtime-closure.js';
 /** The module a `--app node` bundle reaches GI through. */
 const NODE_GI_MODULE = '@gjsify/node-gi/gi';
@@ -44,7 +56,12 @@ const NAMESPACE = /^[A-Za-z][A-Za-z\d_]*$/;
  * specifier pins one and bare `Ns` when it does not.
  */
 export function scanGiNamespaces(source) {
+    return scanGiRequirements(source).namespaces;
+}
+/** {@link scanGiNamespaces}, plus which of them the artifact marks optional (ADR 0087). */
+export function scanGiRequirements(source) {
     const found = new Set();
+    const optional = new Set();
     // TWO SETS, because the two kinds of binding are not interchangeable and
     // treating them as one over-approximated on a real minified bundle. A
     // namespace object (`import * as gi`) and a required module object are only
@@ -89,11 +106,57 @@ export function scanGiNamespaces(source) {
             calls.push(node);
     });
     for (const call of calls) {
+        const marker = optionalMarkerNamespace(call);
+        if (marker !== null) {
+            optional.add(marker);
+            continue;
+        }
         const key = requireGiNamespace(call, callable, objects);
         if (key !== null)
             found.add(key);
     }
-    return [...found].sort();
+    return { namespaces: [...found].sort(), optional: [...optional].filter((ns) => found.has(ns)).sort() };
+}
+/**
+ * The namespace an optional-marker call names, or `null` when this is not one.
+ *
+ * The shape is the bundler's: `globalThis[Symbol.for(GI_OPTIONAL_MARKER)]?.("Ns", "X")`,
+ * matched on BOTH halves rather than on the whole statement — the minifier rewrites
+ * the string literals to backticks and the optional call to a `ChainExpression`
+ * around the `CallExpression` this walk still reaches, and a plain call (a host that
+ * has a handler the minifier could prove is non-null) reads the same way.
+ */
+function optionalMarkerNamespace(call) {
+    const callee = call.callee;
+    if (callee?.type !== 'MemberExpression' || callee.computed !== true)
+        return null;
+    // `globalThis[Symbol.for(KEY)]` — a computed member whose PROPERTY is the
+    // `Symbol.for` call, so the key is an argument of that inner call rather than
+    // of the outer one. Verified against acorn's own shape: `optional` chaining
+    // wraps the whole thing in a `ChainExpression`, which the walk descends into,
+    // so the `CallExpression` reaches this function either way.
+    const keyCall = callee.property;
+    if (keyCall?.type !== 'CallExpression')
+        return null;
+    const keyCallee = keyCall.callee;
+    const keyObject = keyCallee?.type === 'MemberExpression' ? keyCallee.object : undefined;
+    const keyProperty = keyCallee?.type === 'MemberExpression' ? keyCallee.property : undefined;
+    if (keyObject?.type !== 'Identifier' || keyObject.name !== 'Symbol')
+        return null;
+    if (keyProperty?.type !== 'Identifier' || keyProperty.name !== 'for')
+        return null;
+    const keyArgs = keyCall.arguments ?? [];
+    if (staticStringValue(keyArgs[0]) !== GI_OPTIONAL_MARKER)
+        return null;
+    const host = callee.object;
+    if (host?.type !== 'Identifier' || host.name !== 'globalThis')
+        return null;
+    const args = call.arguments ?? [];
+    const namespace = staticStringValue(args[0]);
+    if (namespace === null || !NAMESPACE.test(namespace))
+        return null;
+    const version = staticStringValue(args[1]);
+    return version === null || version === '' ? namespace : `${namespace}-${version}`;
 }
 /** `gi://Gtk?version=4.0` → `Gtk-4.0`; `gi://Gtk` → `Gtk`; anything else → null. */
 export function parseGiSpecifier(specifier) {

package/lib/utils/ship/gzip.js

@@ -26,7 +26,7 @@
 //     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
+// Ledgered in `status/open-todos/README.md`; closing it means pinning ONE deflate
 // implementation, which is a larger decision than this file.
 import { gzip } from '@gjsify/tar';
 /**

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

@@ -157,6 +157,12 @@ export interface RasterizeInput {
      * alone passes just as well when nobody wires it in.
      */
     spawn?: typeof spawnToCompletion;
+    /**
+     * The command a refusal names (default `gjsify ship`). `gjsify webext` renders
+     * its toolbar icons through the same child, and a message blaming `ship`
+     * would send its reader to the wrong command's documentation.
+     */
+    command?: string;
 }
 /**
  * Render an SVG at every size through librsvg, in a child GJS.

package/lib/utils/ship/icons.js

@@ -267,6 +267,7 @@ export function rasterizerEnv(opts = {}) {
 export async function rasterizeSvg(input) {
     if (input.sizes.length === 0)
         return new Map();
+    const command = input.command ?? 'gjsify ship';
     // THE CLI'S OWN SPAWN WRAPPER, not `promisify(execFile)`. Measured under the
     // GJS-built CLI (`dist/cli.gjs.mjs`, gjs 1.88): `node:util`'s `promisify` over
     // `@gjsify/child_process`'s `execFile` resolves with the bare stdout string —
@@ -285,7 +286,7 @@ export async function rasterizeSvg(input) {
         // A 1024 px PNG of a detailed icon is a few hundred kilobytes; base64 adds
         // a third. Node's default 1 MiB is within reach of one large element.
         maxBuffer: 64 * 1024 * 1024,
-        notFound: () => new Error(`gjsify ship: \`${RASTERIZER}\` is not on PATH, and it is what renders ${input.svg} into the ` +
+        notFound: () => new Error(`${command}: \`${RASTERIZER}\` is not on PATH, and it is what renders ${input.svg} into the ` +
             `sizes an icon needs on this OS. ${RASTERIZER_HINT}.`),
     });
     const stdout = result.stdout ?? '';
@@ -296,7 +297,7 @@ export async function rasterizeSvg(input) {
         const hint = /Rsvg|Typelib|cairo/i.test(stderr)
             ? ` The Rsvg typelib or GJS's cairo binding is missing. ${RASTERIZER_HINT}.`
             : '';
-        throw new Error(`gjsify ship: rendering ${input.svg} through ${RASTERIZER} failed (exit ${result.code ?? result.signal}).` +
+        throw new Error(`${command}: rendering ${input.svg} through ${RASTERIZER} failed (exit ${result.code ?? result.signal}).` +
             `${hint}${stderr === '' ? '' : `\n    ${stderr.split('\n').join('\n    ')}`}`);
     }
     let parsed;
@@ -304,19 +305,19 @@ export async function rasterizeSvg(input) {
         parsed = JSON.parse(stdout);
     }
     catch {
-        throw new Error(`gjsify ship: ${RASTERIZER} printed something other than the rendered icon while rendering ` +
+        throw new Error(`${command}: ${RASTERIZER} printed something other than the rendered icon while rendering ` +
             `${input.svg}: ${stdout.slice(0, 200)}`);
     }
     const out = new Map();
     for (const size of input.sizes) {
         const encoded = parsed[String(size)];
         if (encoded === undefined) {
-            throw new Error(`gjsify ship: ${RASTERIZER} rendered no ${size} px image of ${input.svg}.`);
+            throw new Error(`${command}: ${RASTERIZER} rendered no ${size} px image of ${input.svg}.`);
         }
         const png = new Uint8Array(Buffer.from(encoded, 'base64'));
         const { width, height } = readPngSize(png, `the ${size} px render of ${input.svg}`);
         if (width !== size || height !== size) {
-            throw new Error(`gjsify ship: asked ${RASTERIZER} for a ${size} px render of ${input.svg} and got ${width}×${height}.`);
+            throw new Error(`${command}: asked ${RASTERIZER} for a ${size} px render of ${input.svg} and got ${width}×${height}.`);
         }
         out.set(size, png);
     }

package/lib/utils/ship/launcher.js

@@ -171,7 +171,7 @@ function renderPrefixLauncher(settings, bundleRelPath, layout) {
  * IT EXECS WHAT THE BUNDLE CARRIES. `runtime` comes from
  * `utils/ship/app-runtime.ts` and names the interpreter, the relocated GTK
  * closure and the node-gi addon staged inside `Contents/` — so the exec line is
- * `"$here/node"` and the two locators below point into `Contents/Frameworks`.
+ * `"$here/node"` and the two locators below point into `dirs.native`.
  * When the stage carries none of them every line here is byte-identical to what
  * M2a wrote, which is what keeps a bundle assembled without the runtime packages
  * exactly as (un)usable as it was rather than differently broken.
@@ -261,7 +261,7 @@ function renderAppBundleLauncher(settings, bundleRelPath, layout, runtime) {
     // `node_modules`, and a shipped `.app` has neither: its JavaScript is one
     // bundled file under `Contents/Resources/lib`, so `import.meta.url` there
     // resolves node-gi's "package root" to the bundle's directory and every probed
-    // path lands beside the bundle instead of in `Contents/Frameworks`.
+    // path lands beside the bundle instead of in `dirs.native`.
     //
     // `NODE_GI_NATIVE` is the same problem for the addon: `prebuildAddonPath()`
     // joins `prebuilds/<target>/node_gi.node` onto that same wrong root